browser.debugger

ब्यौरा

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

टारगेट

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

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

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

सुरक्षा की वजहों से, browser.debugger एपीआई, Chrome DevTools Protocol के सभी डोमेन को ऐक्सेस करने की अनुमति नहीं देता. ये डोमेन उपलब्ध हैं: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, 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");
  }
});

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

उदाहरण

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

टाइप

Debuggee

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

प्रॉपर्टी

  • extensionId

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

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

  • tabId

    number ज़रूरी नहीं

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

  • 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 ज़रूरी नहीं

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

  • targetId

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

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

DetachReason

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

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

Enum

"target_closed"

"canceled_by_user"

TargetInfo

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

प्रॉपर्टी

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

    बूलियन

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

  • extensionId

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

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

  • faviconUrl

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

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

  • आईडी

    स्ट्रिंग

    टारगेट आईडी.

  • tabId

    number ज़रूरी नहीं

    टैब आईडी, अगर टाइप == '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

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

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

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