chrome.debugger

ब्यौरा

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

अनुमतियां

debugger

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

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

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

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

टारगेट

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

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

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

सुरक्षा की वजहों से, chrome.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 से, chrome.debugger एपीआई फ़्लैट सेशन के साथ काम करता है. इसकी मदद से, अपने मुख्य डीबगर सेशन में बच्चों के तौर पर अन्य टारगेट जोड़े जा सकते हैं. साथ ही, उन्हें 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 से भी अटैच कर दिया जाएगा. हालांकि, यह रिकर्सिव नहीं है. इसलिए, सेशन को 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 प्रोटोकॉल सेशन का ओपेक आईडी. यह कुकी, tabId, extensionId या targetId से पहचाने गए रूट सेशन में मौजूद चाइल्ड सेशन की पहचान करती है.

  • tabId

    number ज़रूरी नहीं

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

  • targetId

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

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

DetachReason

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

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

Enum

"target_closed"

"canceled_by_user"

TargetInfo

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

प्रॉपर्टी

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

    बूलियन

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

  • 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,
  callback?: function,
): Promise<void>

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

पैरामीटर

  • टारगेट

    Debuggee

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

  • requiredVersion

    स्ट्रिंग

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

  • कॉलबैक

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

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

    () => void

रिटर्न

  • Promise<void>

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

detach()

प्रॉमिस 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
): Promise<void>

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

पैरामीटर

  • टारगेट

    Debuggee

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

  • कॉलबैक

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

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

    () => void

रिटर्न

  • Promise<void>

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

getTargets()

प्रॉमिस 
chrome.debugger.getTargets(
  callback?: function,
): Promise<TargetInfo[]>

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

पैरामीटर

  • कॉलबैक

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

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

    (result: TargetInfo[]) => void

    • नतीजा

      TargetInfo[]

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

रिटर्न

  • Promise<TargetInfo[]>

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

sendCommand()

प्रॉमिस 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
): Promise<object | undefined>

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

पैरामीटर

  • टारगेट

    DebuggerSession

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

  • तरीका

    स्ट्रिंग

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

  • commandParams

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

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

  • कॉलबैक

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

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

    (result?: object) => void

    • नतीजा

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

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

रिटर्न

  • 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

    • तरीका

      स्ट्रिंग

    • पैरामीटर

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