chrome.debugger

ब्यौरा

chrome.debugger एपीआई, Chrome के रिमोट डीबगिंग प्रोटोकॉल के लिए, ट्रांसपोर्ट के अन्य विकल्प के तौर पर काम करता है. नेटवर्क इंटरैक्शन को इंस्ट्रूमेंट करने, JavaScript को डीबग करने, डीओएम और सीएसएस में बदलाव करने वगैरह के लिए, एक या उससे ज़्यादा टैब में अटैच करने के लिए chrome.debugger का इस्तेमाल करें. sendCommand की मदद से टैब को टारगेट करने के लिए, Debuggee प्रॉपर्टी tabId का इस्तेमाल करें. साथ ही, onEvent कॉलबैक से tabId के हिसाब से इवेंट को रूट करें.

अनुमतियां

debugger

इस एपीआई का इस्तेमाल करने के लिए, आपको अपने एक्सटेंशन के मेनिफ़ेस्ट में "debugger" अनुमति का एलान करना होगा.

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

कॉन्सेप्ट और इस्तेमाल

अटैच होने के बाद, chrome.debugger एपीआई की मदद से किसी टारगेट को Chrome DevTools प्रोटोकॉल (CDP) निर्देश भेजे जा सकते हैं. इस दस्तावेज़ में, सीडीपी के बारे में पूरी जानकारी नहीं दी गई है. सीडीपी के बारे में ज़्यादा जानने के लिए, सीडीपी का आधिकारिक दस्तावेज़ देखें.

टारगेट

टारगेट, किसी ऐसी चीज़ को दिखाते हैं जिसे डीबग किया जा रहा है. इसमें टैब, 'iframe' या वर्कर्स शामिल हो सकते हैं. हर टारगेट की पहचान यूयूआईडी से की जाती है. साथ ही, उससे जुड़ा एक टाइप होता है, जैसे कि iframe, shared_worker वगैरह.

किसी टारगेट में, एक से ज़्यादा एक्सीक्यूशन कॉन्टेक्स्ट हो सकते हैं. उदाहरण के लिए, एक ही प्रोसेस वाले iframe को यूनीक टारगेट नहीं मिलता, बल्कि उन्हें अलग-अलग कॉन्टेक्स्ट के तौर पर दिखाया जाता है. इन्हें किसी एक टारगेट से ऐक्सेस किया जा सकता है.

प्रतिबंधित डोमेन

सुरक्षा से जुड़ी वजहों से, chrome.debugger API सभी Chrome DevTools प्रोटोकॉल डोमेन का ऐक्सेस नहीं देता. उपलब्ध डोमेन: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio, और WebAuthn.

फ़्रेम के साथ काम करना

फ़्रेम को टारगेट से एक-एक करके मैप नहीं किया जाता. एक ही टैब में, एक ही प्रोसेस के कई फ़्रेम एक ही टारगेट शेयर कर सकते हैं. हालांकि, वे अलग-अलग एक्सीक्यूशन कॉन्टेक्स्ट का इस्तेमाल करते हैं. दूसरी ओर, प्रोसेस से बाहर के iframe के लिए नया टारगेट बनाया जा सकता है.

सभी फ़्रेम में अटैच करने के लिए, आपको हर तरह के फ़्रेम को अलग-अलग हैंडल करना होगा:

  • एक ही प्रोसेस फ़्रेम से जुड़े नए रनटाइम कॉन्टेक्स्ट की पहचान करने के लिए, Runtime.executionContextCreated इवेंट को सुनें.

  • प्रोसेस से बाहर के फ़्रेम की पहचान करने के लिए, मिलते-जुलते टारगेट से अटैच करने का तरीका अपनाएं.

किसी टारगेट से कनेक्ट करने के बाद, हो सकता है कि आप उससे जुड़े अन्य टारगेट से भी कनेक्ट करना चाहें. इनमें, प्रोसेस से बाहर के चाइल्ड फ़्रेम या उससे जुड़े वर्कर्स शामिल हैं.

Chrome 125 से, chrome.debugger API फ़्लैट सेशन के साथ काम करता है. इसकी मदद से, अपने मुख्य डीबगर सेशन में अन्य टारगेट को चाइल्ड के तौर पर जोड़ा जा सकता है. साथ ही, chrome.debugger.attach को फिर से कॉल किए बिना उन्हें मैसेज भेजा जा सकता है. इसके बजाय, chrome.debugger.sendCommand को कॉल करते समय sessionId प्रॉपर्टी जोड़ी जा सकती है. इससे उस चाइल्ड टारगेट की पहचान की जा सकती है जिसे आपको निर्देश भेजना है.

प्रोसेस में न होने वाले चाइल्ड फ़्रेम से अपने-आप अटैच होने के लिए, पहले Target.attachedToTarget इवेंट के लिए एक लिसनर जोड़ें:

chrome.debugger.onEvent.addListener((source, method, params) => {
  if (method === "Target.attachedToTarget") {
    // `source` identifies the parent session, but we need to construct a new
    // identifier for the child session
    const session = { ...source, sessionId: params.sessionId };

    // Call any needed CDP commands for the child session
    await chrome.debugger.sendCommand(session, "Runtime.enable");
  }
});

इसके बाद, Target.setAutoAttach कमांड भेजकर अपने-आप अटैच होने की सुविधा चालू करें. साथ ही, flatten विकल्प को true पर सेट करें:

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

अपने-आप अटैच होने की सुविधा सिर्फ़ उन फ़्रेम से जुड़ी होती है जिनके बारे में टारगेट को पता होता है. यह सुविधा सिर्फ़ उन फ़्रेम तक सीमित होती है जो उससे जुड़े फ़्रेम के चाइल्ड फ़्रेम होते हैं. उदाहरण के लिए, A -> B -> C फ़्रेम हैरारकी (जहां सभी क्रॉस-ऑरिजिन हैं) में, A से जुड़े टारगेट के लिए Target.setAutoAttach को कॉल करने पर, सेशन को B से भी अटैच कर दिया जाएगा. हालांकि, यह बार-बार नहीं होता है. इसलिए, B को सेशन को C से अटैच करने के लिए, Target.setAutoAttach को भी कॉल करना होगा.

उदाहरण

इस एपीआई को आज़माने के लिए, chrome-extension-samples रिपॉज़िटरी से डीबगर एपीआई का उदाहरण इंस्टॉल करें.

टाइप

Debuggee

डीबग किए जा रहे प्रोग्राम का आइडेंटिफ़ायर. tabId, extensionId या targetId में से किसी एक की जानकारी देना ज़रूरी है

प्रॉपर्टी

  • extensionId

    स्ट्रिंग ज़रूरी नहीं है

    उस एक्सटेंशन का आईडी जिसे डीबग करना है. एक्सटेंशन के बैकग्राउंड पेज से अटैच करने के लिए, --silent-debugger-extension-api कमांड-लाइन स्विच का इस्तेमाल करना ज़रूरी है.

  • tabId

    number ज़रूरी नहीं

    उस टैब का आईडी जिसे आपको डीबग करना है.

  • targetId

    स्ट्रिंग ज़रूरी नहीं है

    डीबग टारगेट का ओपेक आईडी.

DebuggerSession

Chrome 125 और उसके बाद के वर्शन

डीबगर सेशन आइडेंटिफ़ायर. tabId, extensionId या targetId में से कोई एक दिया जाना चाहिए. इसके अलावा, sessionId भी दिया जा सकता है. हालांकि, ऐसा करना ज़रूरी नहीं है. अगर onEvent से भेजे गए आर्ग्युमेंट के लिए sessionId तय किया गया है, तो इसका मतलब है कि इवेंट, रूट डीबग किए जा रहे सेशन में मौजूद चाइल्ड प्रोटोकॉल सेशन से आ रहा है. अगर sendCommand को पास करते समय sessionId तय किया जाता है, तो यह रूट डीबग किए जा रहे सेशन में चाइल्ड प्रोटोकॉल सेशन को टारगेट करता है.

प्रॉपर्टी

  • extensionId

    स्ट्रिंग ज़रूरी नहीं है

    उस एक्सटेंशन का आईडी जिसे डीबग करना है. एक्सटेंशन के बैकग्राउंड पेज से अटैच करने के लिए, --silent-debugger-extension-api कमांड-लाइन स्विच का इस्तेमाल करना ज़रूरी है.

  • sessionId

    स्ट्रिंग ज़रूरी नहीं है

    Chrome DevTools प्रोटोकॉल सेशन का ओपेक आईडी. tabId, extensionId या targetId से पहचाने गए रूट सेशन में चाइल्ड सेशन की पहचान करता है.

  • tabId

    number ज़रूरी नहीं

    उस टैब का आईडी जिसे आपको डीबग करना है.

  • targetId

    स्ट्रिंग ज़रूरी नहीं है

    डीबग टारगेट का ओपेक आईडी.

DetachReason

Chrome 44 और उसके बाद के वर्शन

कनेक्शन खत्म होने की वजह.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

टारगेट की डीबग जानकारी

प्रॉपर्टी

  • अटैच किया गया

    बूलियन

    अगर डीबगर पहले से अटैच है, तो True.

  • extensionId

    स्ट्रिंग ज़रूरी नहीं है

    एक्सटेंशन आईडी, जो तब तय किया जाता है, जब टाइप = 'background_page' हो.

  • faviconUrl

    स्ट्रिंग ज़रूरी नहीं है

    टारगेट फ़ेविकॉन का यूआरएल.

  • आईडी

    स्ट्रिंग

    टारगेट आईडी.

  • tabId

    number ज़रूरी नहीं

    टैब आईडी, जो तब तय किया जाता है, जब type == 'page' हो.

  • title

    स्ट्रिंग

    टारगेट पेज का टाइटल.

  • टाइप

    TargetInfoType

    टारगेट टाइप.

  • url

    स्ट्रिंग

    टारगेट यूआरएल.

TargetInfoType

Chrome 44 और उसके बाद के वर्शन

टारगेट टाइप.

Enum

"page"

"background_page"

"worker"

"other"

तरीके

attach()

वादा करना 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

दिए गए टारगेट में डीबगर को अटैच करता है.

पैरामीटर

  • टारगेट

    Debuggee

    डीबगिंग टारगेट, जिसे आपको अटैच करना है.

  • requiredVersion

    स्ट्रिंग

    डीबगिंग प्रोटोकॉल का ज़रूरी वर्शन ("0.1"). डिबग किए जा रहे ऐप्लिकेशन के मेजर वर्शन और माइनर वर्शन से मेल खाने वाले वर्शन का ही इस्तेमाल किया जा सकता है. प्रोटोकॉल के वर्शन की सूची यहां देखी जा सकती है.

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    callback पैरामीटर इस तरह दिखता है: 

    () => void

रिटर्न

  • Promise<void>

    Chrome 96 और उसके बाद के वर्शन

    मेनिफ़ेस्ट के तीसरे वर्शन और उसके बाद के वर्शन में, प्रॉमिस का इस्तेमाल किया जा सकता है. हालांकि, पुराने सिस्टम के साथ काम करने की सुविधा के लिए कॉलबैक उपलब्ध कराए गए हैं. एक ही फ़ंक्शन कॉल में, दोनों का इस्तेमाल नहीं किया जा सकता. प्रोमिस, कॉलबैक में पास किए गए टाइप के साथ ही रिज़ॉल्व होता है.

detach()

वादा करना 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

दिए गए टारगेट से डीबगर को हटाता है.

पैरामीटर

  • टारगेट

    Debuggee

    डीबगिंग टारगेट, जिसे आपको डिटैच करना है.

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    callback पैरामीटर इस तरह दिखता है: 

    () => void

रिटर्न

  • Promise<void>

    Chrome 96 और उसके बाद के वर्शन

    मेनिफ़ेस्ट के तीसरे वर्शन और उसके बाद के वर्शन में, प्रॉमिस का इस्तेमाल किया जा सकता है. हालांकि, पुराने सिस्टम के साथ काम करने की सुविधा के लिए कॉलबैक उपलब्ध कराए गए हैं. एक ही फ़ंक्शन कॉल में, दोनों का इस्तेमाल नहीं किया जा सकता. प्रोमिस, कॉलबैक में पास किए गए टाइप के साथ ही रिज़ॉल्व होता है.

getTargets()

वादा करना 
chrome.debugger.getTargets(
  callback?: function,
)

उपलब्ध डीबग टारगेट की सूची दिखाता है.

पैरामीटर

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    callback पैरामीटर इस तरह दिखता है: 

    (result: TargetInfo[]) => void

    • नतीजा

      TargetInfo[]

      उपलब्ध डीबग टारगेट से जुड़े TargetInfo ऑब्जेक्ट का कलेक्शन.

रिटर्न

  • Promise<TargetInfo[]>

    Chrome 96 और उसके बाद के वर्शन

    मेनिफ़ेस्ट के तीसरे वर्शन और उसके बाद के वर्शन में, प्रॉमिस का इस्तेमाल किया जा सकता है. हालांकि, पुराने सिस्टम के साथ काम करने की सुविधा के लिए कॉलबैक उपलब्ध कराए गए हैं. एक ही फ़ंक्शन कॉल में, दोनों का इस्तेमाल नहीं किया जा सकता. प्रोमिस, कॉलबैक में पास किए गए टाइप के साथ ही रिज़ॉल्व होता है.

sendCommand()

वादा करना 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

डीबगिंग टारगेट को दिया गया निर्देश भेजता है.

पैरामीटर

  • टारगेट

    DebuggerSession

    डीबगिंग टारगेट, जिस पर आपको कमांड भेजना है.

  • तरीका

    स्ट्रिंग

    तरीके का नाम. यह रिमोट डीबगिंग प्रोटोकॉल में बताए गए तरीकों में से कोई एक होना चाहिए.

  • commandParams

    ऑब्जेक्ट ज़रूरी नहीं है

    अनुरोध पैरामीटर वाला JSON ऑब्जेक्ट. यह ऑब्जेक्ट, दिए गए तरीके के लिए रिमोट डीबगिंग पैरामीटर स्कीम के मुताबिक होना चाहिए.

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    callback पैरामीटर इस तरह दिखता है: 

    (result?: object) => void

    • नतीजा

      ऑब्जेक्ट ज़रूरी नहीं है

      रिस्पॉन्स वाला JSON ऑब्जेक्ट. रिस्पॉन्स का स्ट्रक्चर, तरीके के नाम के हिसाब से अलग-अलग होता है. इसे रिमोट डीबगिंग प्रोटोकॉल में, कमांड के ब्यौरे के 'रिटर्न' एट्रिब्यूट से तय किया जाता है.

रिटर्न

  • Promise<object | undefined>

    Chrome 96 और उसके बाद के वर्शन

    मेनिफ़ेस्ट के तीसरे वर्शन और उसके बाद के वर्शन में, प्रॉमिस का इस्तेमाल किया जा सकता है. हालांकि, पुराने सिस्टम के साथ काम करने की सुविधा के लिए कॉलबैक उपलब्ध कराए गए हैं. एक ही फ़ंक्शन कॉल में, दोनों का इस्तेमाल नहीं किया जा सकता. प्रोमिस, कॉलबैक में पास किए गए टाइप के साथ ही रिज़ॉल्व होता है.

इवेंट

onDetach

chrome.debugger.onDetach.addListener(
  callback: function,
)

जब ब्राउज़र, टैब के लिए डीबगिंग सेशन को बंद करता है, तब यह ट्रिगर होता है. ऐसा तब होता है, जब टैब बंद किया जा रहा हो या अटैच किए गए टैब के लिए Chrome DevTools को चालू किया जा रहा हो.

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

    callback पैरामीटर इस तरह दिखता है: 

    (source: Debuggee, reason: DetachReason) => void

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

टारगेट की समस्याओं के इंस्ट्रूमेंटेशन इवेंट को डीबग करते समय ट्रिगर होता है.

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

    callback पैरामीटर इस तरह दिखता है: 

    (source: DebuggerSession, method: string, params?: object) => void

    • तरीका

      स्ट्रिंग

    • पैरामीटर

      ऑब्जेक्ट ज़रूरी नहीं है