browser.debugger

ब्यौरा

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

अनुमतियां

debugger

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

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

Enterprise की नीति से जुड़ी पाबंदियां

एंटरप्राइज़ डिवाइसों पर, कुछ नीतियां एक्सटेंशन को अटैच करने के समय, डिबगर को अटैच करने से रोक सकती हैं. इसके लिए, अटैच करने के समय, सभी या किसी भी मॉडल का इस्तेमाल किया जा सकता है (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 प्रोटोकॉल (सीडीपी) कमांड भेजी जा सकती हैं. इस दस्तावेज़ में, सीडीपी के बारे में पूरी जानकारी नहीं दी गई है. सीडीपी के बारे में ज़्यादा जानने के लिए, सीडीपी का आधिकारिक दस्तावेज़ देखें.

टारगेट

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

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

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

सुरक्षा की वजहों से, browser.debugger एपीआई, 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 और इसके बाद के वर्शन में, browser.debugger API फ़्लैट सेशन के साथ काम करता है. इसकी मदद से, अपने मुख्य डीबगर सेशन में बच्चों के तौर पर अन्य टारगेट जोड़े जा सकते हैं. साथ ही, उन्हें 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");
  }
});

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

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 से भी अटैच कर दिया जाएगा. हालांकि, यह रिकर्सिव नहीं है. इसलिए, सेशन को C से अटैच करने के लिए Target.setAutoAttach को भी कॉल करना होगा.

उदाहरण

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

टाइप

Debuggee

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

प्रॉपर्टी

  • extensionId

    string ज़रूरी नहीं है

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

  • tabId

    number optional

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

  • targetId

    string ज़रूरी नहीं है

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

DebuggerSession

Chrome 125 या इसके बाद का वर्शन

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

प्रॉपर्टी

  • extensionId

    string ज़रूरी नहीं है

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

  • sessionId

    string ज़रूरी नहीं है

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

  • tabId

    number optional

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

  • targetId

    string ज़रूरी नहीं है

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

DetachReason

Chrome 44 या इसके बाद का वर्शन

कनेक्शन बंद होने की वजह.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

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

प्रॉपर्टी

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

    बूलियन

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

  • extensionId

    string ज़रूरी नहीं है

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

  • faviconUrl

    string ज़रूरी नहीं है

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

  • आईडी

    स्ट्रिंग

    टारगेट आईडी.

  • tabId

    number optional

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

  • title

    स्ट्रिंग

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

  • टाइप

    TargetInfoType

    टारगेट टाइप.

  • url

    स्ट्रिंग

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

TargetInfoType

Chrome 44 या इसके बाद का वर्शन

टारगेट टाइप.

Enum

"page"

"background_page"

"worker"

"other"

तरीके

attach()

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

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

पैरामीटर

  • टारगेट

    Debuggee

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

  • requiredVersion

    स्ट्रिंग

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

रिटर्न

  • Promise<void>

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

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

detach()

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

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

पैरामीटर

  • टारगेट

    Debuggee

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

रिटर्न

  • Promise<void>

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

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

getTargets()

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

इससे डीबग करने के लिए उपलब्ध टारगेट की सूची मिलती है.

रिटर्न

  • Promise<TargetInfo[]>

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

sendCommand()

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

यह कमांड, डीबग करने के लिए चुने गए टारगेट को भेजी जाती है.

पैरामीटर

  • टारगेट

    DebuggerSession

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

  • तरीका

    स्ट्रिंग

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

  • commandParams

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

    अनुरोध के पैरामीटर वाला 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

    • सोर्स

      DebuggerSession

    • तरीका

      स्ट्रिंग

    • params

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