chrome.debugger

ब्यौरा

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

अनुमतियां

debugger

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

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

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

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

टारगेट

टारगेट, ऐसी चीज़ों को कहते हैं जिन्हें डीबग किया जा रहा है. इनमें टैब, iframe या वर्कर शामिल हो सकते हैं. हर टारगेट की पहचान यूयूआईडी से होती है. साथ ही, इससे जुड़ा एक टाइप होता है. जैसे, 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,
): 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

  • सोर्स

    Debuggee

  • वजह

    DetachReason

onEvent

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

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

पैरामीटर

• कॉलबैक

  फ़ंक्शन

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

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

  • सोर्स

    DebuggerSession

  • तरीका

    स्ट्रिंग

  • params

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