chrome.debugger

ब्यौरा

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

अनुमतियां

debugger

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

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

उद्यम नीति प्रतिबंध

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

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

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

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

टारगेट

टारगेट, ऐसी चीज़ों को कहते हैं जिन्हें डीबग किया जा रहा है. इनमें टैब, iframe या वर्कर शामिल हो सकते हैं. प्रत्येक लक्ष्य को एक UUID द्वारा पहचाना जाता है और उससे संबंधित एक प्रकार होता है (जैसे iframe, shared_worker, और अधिक).

किसी लक्ष्य के भीतर, कई निष्पादन संदर्भ हो सकते हैं - उदाहरण के लिए, एक ही प्रक्रिया के आईफ्रेम को एक अद्वितीय लक्ष्य नहीं मिलता है, बल्कि उन्हें अलग-अलग संदर्भों के रूप में दर्शाया जाता है जिन्हें एक ही लक्ष्य से एक्सेस किया जा सकता है.

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

सुरक्षा की वजहों से, 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 रनटाइम, स्टोरेज, टारगेट, ट्रेसिंग, WebAudio, और WebAuthn.

फ़्रेम का इस्तेमाल करना

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

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

  • एक ही प्रक्रिया फ्रेम से जुड़े नए निष्पादन संदर्भों की पहचान करने के लिए Runtime.executionContextCreated घटना को सुनें.

  • प्रक्रिया से बाहर के फ़्रेमों की पहचान करने के लिए संबंधित लक्ष्यों से जुड़ें के चरणों का पालन करें.

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

Chrome 125 से शुरू होकर, chrome.debugger API फ्लैट सेशन का समर्थन करता है. यह आपको अपने मुख्य डिबगर सत्र में अतिरिक्त लक्ष्यों को बच्चों के रूप में जोड़ने और 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 से जोड़ने के लिए B के लिए Target.setAutoAttach को भी कॉल करने की आवश्यकता है.

उदाहरण

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

टाइप

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

    एक्सटेंशन आईडी, जो टाइप = 'बैकग्राउंड_पेज' होने पर परिभाषित होती है.

  • faviconUrl

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

    लक्षित फ़ेविकॉन यूआरएल.

  • आईडी

    स्ट्रिंग

    लक्ष्य आईडी.

  • tabId

    number optional

    टैब आईडी, जो कि टाइप == 'पेज' होने पर परिभाषित होती है.

  • title

    स्ट्रिंग

    लक्षित पृष्ठ शीर्षक.

  • टाइप

    TargetInfoType

    लक्ष्य प्रकार.

  • url

    स्ट्रिंग

    लक्ष्य यूआरएल.

TargetInfoType

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

लक्ष्य प्रकार.

Enum

"पृष्ठ"

"पृष्ठपृष्ठ"

"कार्यकर्ता"

"अन्य"

तरीके

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[]>

उपलब्ध डिबग लक्ष्यों की सूची लौटाता है.

रिटर्न

sendCommand()

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

दिए गए कमांड को डिबगिंग लक्ष्य पर भेजता है.

पैरामीटर

  • टारगेट

    DebuggerSession

    वह डिबगिंग लक्ष्य जिसे आप कमांड भेजना चाहते हैं.

  • तरीका

    स्ट्रिंग

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

  • commandParams

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

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

रिटर्न

  • वादा<वस्तु | अपरिभाषित>

    क्रोम 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

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