browser.debugger

ब्यौरा

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

अनुमतियां

debugger

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

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

एंटरप्राइज़ की नीति से जुड़ी पाबंदियां

एंटरप्राइज़ डिवाइसों पर, कुछ नीतियां एक्सटेंशन को डीबगर अटैच करने से रोक सकती हैं. इसके लिए, अटैच करते समय ऑल-ऑर-नथिंग मॉडल का इस्तेमाल किया जाता है (browser.debugger.attach()):

• होस्ट से जुड़ी पाबंदियां: अगर एंटरप्राइज़ नीति ExtensionSettings, किसी एक्सटेंशन के लिए ब्लॉक किए गए होस्ट (runtime_blocked_hosts) को कॉन्फ़िगर करती है, तो browser.debugger.attach() को सभी टारगेट पर ब्लॉक कर दिया जाता है. साथ ही, गड़बड़ी का यह मैसेज दिखता है: "Host access is restricted by policy." (भले ही, अलग-अलग ऑरिजिन runtime_allowed_hosts में हों).
• स्क्रीनशॉट और डीएलपी से जुड़ी नीतियां: अगर एंटरप्राइज़ की नीति DisableScreenshots के तहत, स्क्रीनशॉट कैप्चर करने की सुविधा बंद है या टारगेट पर डेटा लीक होने की रोकथाम (डीएलपी) के नियम लागू होते हैं, तो browser.debugger.attach() काम नहीं करता और गड़बड़ी "Screenshot capture is restricted by policy." दिखती है.

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

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

टारगेट

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

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

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

सुरक्षा की वजहों से, browser.debugger एपीआई सभी Chrome DevTools प्रोटोकॉल डोमेन का ऐक्सेस नहीं देता. उपलब्ध डोमेन ये हैं: सुलभता, ऑडिट, CacheStorage, कंसोल, सीएसएस, डेटाबेस, डीबगर, DOM, DOMDebugger, DOMSnapshot, एम्युलेशन, फ़ेच, IO, इनपुट, इंस्पेक्टर, लॉग, नेटवर्क, ओवरले, पेज, परफ़ॉर्मेंस, रनटाइम, स्टोरेज, टारगेट, ट्रेसिंग, WebAudio, और WebAuthn.

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

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

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

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

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

मिलते-जुलते टारगेट से अटैच करना

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

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

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

browser.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 browser.debugger.sendCommand(session, "Runtime.enable");
  }
});

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

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

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

उदाहरण

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

टाइप

Debuggee

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

प्रॉपर्टी

• extensionId

  string ज़रूरी नहीं

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

• tabId

  number ज़रूरी नहीं

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

• targetId

  string ज़रूरी नहीं

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

DebuggerSession

Chrome 125+ browser.* Chrome 148 से

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

प्रॉपर्टी

• extensionId

  string ज़रूरी नहीं

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

• sessionId

  string ज़रूरी नहीं

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

• tabId

  number ज़रूरी नहीं

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

• targetId

  string ज़रूरी नहीं

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

DetachReason

Chrome 44+ browser.* Chrome 148 के बाद से

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

Enum

"target_closed"

"canceled_by_user"

TargetInfo

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

प्रॉपर्टी

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

  बूलियन

  अगर डीबगर पहले से अटैच है, तो वैल्यू true होगी.

• extensionId

  string ज़रूरी नहीं

  एक्सटेंशन आईडी, अगर type = 'background_page' के तौर पर तय किया गया है.

• faviconUrl

  string ज़रूरी नहीं

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

• आईडी

  स्ट्रिंग

  टारगेट आईडी.

• tabId

  number ज़रूरी नहीं

  टैब आईडी, अगर टाइप == 'पेज' के तौर पर तय किया गया है.

• title

  स्ट्रिंग

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

• टाइप

  TargetInfoType

  टारगेट टाइप.

• url

  स्ट्रिंग

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

TargetInfoType

Chrome 44+ browser.* Chrome 148 के बाद से

टारगेट टाइप.

Enum

"page"

"background_page"

"worker"

"other"

तरीके

attach()

browser.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

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

पैरामीटर

• टारगेट

  डीबगी

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

• requiredVersion

  स्ट्रिंग

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

रिटर्न

• वादा<शून्य>

  Chrome 96+ Chrome 148 से browser.*

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

detach()

browser.debugger.detach(
  target: Debuggee,
): Promise<void>

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

पैरामीटर

• टारगेट

  डीबगी

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

रिटर्न

• वादा<शून्य>

  Chrome 96+ Chrome 148 से browser.*

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

getTargets()

browser.debugger.getTargets(): Promise<TargetInfo[]>

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

रिटर्न

• Promise<TargetInfo[]>

  Chrome 96+ Chrome 148 से browser.*

sendCommand()

browser.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

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

पैरामीटर

• टारगेट

  DebuggerSession

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

• तरीका

  स्ट्रिंग

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

• commandParams

  object ज़रूरी नहीं

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

रिटर्न

• Promise<object | undefined>

  Chrome 96+ Chrome 148 से browser.*

  जवाब का मुख्य हिस्सा. अगर मैसेज पोस्ट करते समय कोई गड़बड़ी होती है, तो प्रॉमिस को अस्वीकार कर दिया जाएगा.

इवेंट

onDetach

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

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

पैरामीटर

• कॉलबैक

  फ़ंक्शन

  callback पैरामीटर कुछ ऐसा दिखता है:

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

  • सोर्स

    डीबगी

  • reason

    DetachReason

onEvent

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

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

पैरामीटर

• कॉलबैक

  फ़ंक्शन

  callback पैरामीटर कुछ ऐसा दिखता है:

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

  • सोर्स

    DebuggerSession

  • तरीका

    स्ट्रिंग

  • पैरामीटर

    object ज़रूरी नहीं