browser.debugger

شرح

chrome.debugger API به‌عنوان انتقال جایگزین برای پروتکل اشکال‌زدایی از راه دور Chrome عمل می‌کند. از chrome.debugger برای پیوست کردن به یک یا چند برگه برای ابزارسازی تعامل شبکه، اشکال‌زدایی جاوا اسکریپت، تغییر DOM و CSS، و موارد دیگر استفاده کنید. از ویژگی Debuggee tabId برای هدف‌یابی برگه‌ها با sendCommand و مسیریابی رویدادها با tabId از فراخوانی‌های برگشتی onEvent استفاده کنید.

اجازه‌ها

debugger

برای استفاده از این میانای برنامه‌سازی کاربردی، باید اجازه "debugger" را در مانیفست افزونه‌تان اعلام کنید.

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

محدودیت‌های خط‌مشی سازمانی

در دستگاه‌های سازمانی، برخی‌از خط‌مشی‌ها می‌توانند افزونه‌ها را از پیوست کردن اشکال‌زدا بااستفاده از مدل «همه یا هیچ» در زمان پیوست کردن محدود کنند (browser.debugger.attach()):

• محدودیت‌های میزبان: اگر خط‌مشی سازمانی ExtensionSettings میزبان‌های مسدودشده (runtime_blocked_hosts) را برای افزونه‌ای پیکربندی کند، browser.debugger.attach() در همه هدف‌ها با خطای "Host access is restricted by policy." مسدود می‌شود (حتی اگر مبدأهای تکی در runtime_allowed_hosts باشند).
• خط‌مشی‌های نماگرفت و DLP: اگر خط‌مشی سازمانی DisableScreenshots ضبط نماگرفت را غیرفعال کند یا قوانین «جلوگیری از ازبین رفتن داده‌ها» (DLP) برای هدف اعمال شود، browser.debugger.attach() با خطای "Screenshot capture is restricted by policy." ناموفق می‌شود.

مفاهیم و کاربرد

پس‌از پیوست شدن، browser.debugger API به شما امکان می‌دهد فرمان‌های پروتکل Chrome DevTools (CDP) را به هدف مشخصی ارسال کنید. توضیح عمیق CDP خارج از محدوده این سند است—برای کسب اطلاعات بیشتر درباره CDP، به سند رسمی CDP مراجعه کنید.

هدف‌ها

هدف‌ها نشان‌دهنده چیزی هستند که درحال اشکال‌زدایی است—این می‌تواند شامل برگه، iframe، یا worker باشد. هر هدف با یک شناسه منحصربه‌فرد جهانی (UUID) شناسایی می‌شود و نوع مرتبطی دارد (مانند iframe، shared_worker، و غیره).

درون یک هدف، ممکن است چندین زمینه اجرا وجود داشته باشد—برای مثال، iframeهای همان فرایند هدف یکتایی دریافت نمی‌کنند، بلکه به‌عنوان زمینه‌های مختلفی نمایش داده می‌شوند که می‌توان از یک هدف واحد به آن‌ها دسترسی داشت.

دامنه‌های محدودشده

به‌دلایل امنیتی، browser.debugger API دسترسی به همه دامنه‌های پروتکل Chrome DevTools را فراهم نمی‌کند. دامنه‌های دردسترس عبارت‌اند از: دسترس‌پذیری، بازرسی‌ها، CacheStorage، کنسول، CSS، پایگاه داده، اشکال‌زدا، DOM، DOMDebugger، DOMSnapshot، شبیه‌سازی، Fetch، IO، ورودی، بازرس، گزارش، شبکه، هم‌پوشانی، صفحه، عملکرد، زمان اجرا، فضای ذخیره‌سازی، هدف، ردیابی، WebAudio، و WebAuthn.

کار با قاب‌ها

نگاشت یک‌به‌یک از قاب‌ها به هدف‌ها وجود ندارد. در یک برگه، چندین قاب فرایند یکسان ممکن است هدف یکسانی را هم‌رسانی کنند اما از بافت اجرای متفاوتی استفاده کنند. ازسوی دیگر، ممکن است هدف جدیدی برای iframe خارج از فرایند ایجاد شود.

برای پیوست کردن به همه قاب‌ها، باید هر نوع قاب را به‌طور جداگانه مدیریت کنید:

• به رویداد Runtime.executionContextCreated گوش دهید تا زمینه‌های اجرای جدید مرتبط با همان قاب‌های فرایند را شناسایی کنید.

• مراحل پیوست کردن به هدف‌های مرتبط را دنبال کنید تا قاب‌های خارج از فرایند را شناسایی کنید.

پیوست کردن به هدف‌های مرتبط

پس‌از اتصال به هدف، ممکن است بخواهید به اهداف مرتبط بیشتری متصل شوید، ازجمله قاب‌های فرزند خارج از فرایند یا کارگران مرتبط.

از Chrome نسخه ۱۲۵ به بعد، 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 (که همه میان‌مبدئی هستند)، فراخوانی Target.setAutoAttach برای هدف مرتبط با A منجر به این می‌شود که جلسه به B نیز پیوست شود. اما این بازگشتی نیست، بنابراین Target.setAutoAttach نیز باید برای B فراخوانی شود تا جلسه را به C متصل کند.

مثال‌ها

برای امتحان کردن این میانای برنامه‌سازی کاربردی، نمونه میانای برنامه‌سازی کاربردی اشکال‌زدا را از مخزن chrome-extension-samples نصب کنید.

انواع

Debuggee

شناسه اشکال‌زدایی. باید tabId،‏ extensionId، یا targetId مشخص شود

مشخصات

• extensionId

  رشته اختیاری

  شناسه افزونه‌ای که می‌خواهید اشکال‌زدایی کنید. پیوست کردن به صفحه پس‌زمینه افزونه فقط زمانی امکان‌پذیر است که از کلید خط فرمان --silent-debugger-extension-api استفاده شود.

• tabId

  شماره اختیاری

  شناسه برگه‌ای که می‌خواهید اشکال‌زدایی کنید.

• targetId

  رشته اختیاری

  شناسه مبهم هدف اشکال‌زدایی.

DebuggerSession

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

شناسه جلسه اشکال‌زدا. یکی‌از tabId،‏ extensionId، یا targetId باید مشخص شود. علاوه‌براین، sessionId اختیاری می‌تواند ارائه شود. اگر sessionId برای آرگومان‌های ارسال‌شده از onEvent مشخص شده باشد، به این معنی است که رویداد از یک جلسه پروتکل فرزند در جلسه اشکال‌زدایی ریشه می‌آید. اگر sessionId هنگام ارسال به sendCommand مشخص شده باشد، یک جلسه پروتکل فرزند را در جلسه اشکال‌زدایی ریشه هدف قرار می‌دهد.

مشخصات

• extensionId

  رشته اختیاری

  شناسه افزونه‌ای که می‌خواهید اشکال‌زدایی کنید. پیوست کردن به صفحه پس‌زمینه افزونه فقط زمانی امکان‌پذیر است که از کلید خط فرمان --silent-debugger-extension-api استفاده شود.

• sessionId

  رشته اختیاری

  شناسه مبهم جلسه پروتکل Chrome DevTools. جلسه فرزند را در جلسه ریشه که با tabId،‏ extensionId، یا targetId شناسایی شده است شناسایی می‌کند.

• tabId

  شماره اختیاری

  شناسه برگه‌ای که می‌خواهید اشکال‌زدایی کنید.

• targetId

  رشته اختیاری

  شناسه مبهم هدف اشکال‌زدایی.

DetachReason

Chrome نسخه ۴۴ و بالاتر browser.* از Chrome نسخه ۱۴۸

دلیل قطع اتصال.

شمارشی

"target_closed"

"canceled_by_user"

TargetInfo

اطلاعات هدف اشکال‌زدایی

مشخصات

• پیوست‌شده

  بولی

  اگر اشکال‌زدا ازقبل پیوست شده باشد، درست است.

• extensionId

  رشته اختیاری

  شناسه افزونه، اگر نوع = «background_page» باشد تعریف می‌شود.

• faviconUrl

  رشته اختیاری

  نشانی وب نماد وب‌سایت هدف.

• id

  رشته

  شناسه هدف.

• tabId

  شماره اختیاری

  شناسه برگه، اگر نوع == «صفحه» باشد تعریف می‌شود.

• عنوان

  رشته

  عنوان صفحه هدف.

• نوع

  TargetInfoType

  نوع هدف.

• نشانی وب

  رشته

  نشانی وب هدف.

TargetInfoType

Chrome نسخه ۴۴ و بالاتر browser.* از Chrome نسخه ۱۴۸

نوع هدف.

شمارشی

«صفحه»

"background_page"

«worker»

«دیگر»

روش‌ها

attach()

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

اشکال‌زدا را به هدف ارائه‌شده پیوست می‌کند.

پارامترها

• هدف

  Debuggee

  هدف اشکال‌زدایی که می‌خواهید به آن متصل شوید.

• requiredVersion

  رشته

  نسخه پروتکل اشکال‌زدایی الزامی («0.1»). فقط می‌توان به اشکال‌زدایی با نسخه اصلی منطبق و نسخه فرعی بزرگ‌تر یا مساوی متصل شد. فهرست نسخه‌های پروتکل را می‌توانید در اینجا دریافت کنید.

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

  وقتی عملیات پیوست کردن موفق یا ناموفق باشد، حل می‌شود. این وعده بدون هیچ مقداری حل می‌شود. اگر پیوست کردن ناموفق باشد، وعده رد خواهد شد.

detach()

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

اشکال‌زدا را از هدف موردنظر جدا می‌کند.

پارامترها

• هدف

  Debuggee

  هدف اشکال‌زدایی که می‌خواهید از آن جدا شوید.

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

  وقتی عملیات جدا کردن موفق یا ناموفق باشد، حل می‌شود. این وعده بدون هیچ مقداری حل می‌شود. اگر جدا کردن ناموفق باشد، وعده رد خواهد شد.

getTargets()

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

فهرست هدف‌های اشکال‌زدایی دردسترس را برمی‌گرداند.

بازگشتی‌ها

• Promise<TargetInfo[]>

  Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

sendCommand()

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

فرمان داده‌شده را به هدف اشکال‌زدایی ارسال می‌کند.

پارامترها

• هدف

  DebuggerSession

  هدف اشکال‌زدایی که می‌خواهید فرمان به آن ارسال شود.

• روش

  رشته

  نام روش. باید یکی از روش‌های تعریف‌شده توسط پروتکل اشکال‌زدایی ازراه‌دور باشد.

• commandParams

  شیء اختیاری

  شیء JSON با پارامترهای درخواست. این شیء باید با طرح پارامترهای اشکال‌زدایی از راه دور برای روش ارائه‌شده مطابقت داشته باشد.

بازگشتی‌ها

• Promise<object | undefined>

  Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

  متن پاسخ. اگر هنگام پست کردن پیام خطایی رخ دهد، promise رد خواهد شد.

رویدادها

onDetach

browser.debugger.onDetach.addListener(
  callback: function,
)

وقتی مرورگر جلسه اشکال‌زدایی را برای برگه خاتمه می‌دهد، فعال می‌شود. این اتفاق زمانی رخ می‌دهد که برگه درحال بسته شدن باشد یا Chrome DevTools برای برگه پیوست‌شده فراخوانی شود.

پارامترها

• تماس برگشتی

  عملکرد

  پارامتر callback به‌صورت زیر است:

  (source: Debuggee, reason: DetachReason) => void

  • منبع

    Debuggee

  • دلیل

    DetachReason

onEvent

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

هرگاه هدف اشکال‌زدایی رویداد ابزارسازی را صادر کند، فعال می‌شود.

پارامترها

• تماس برگشتی

  عملکرد

  پارامتر callback به‌صورت زیر است:

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

  • منبع

    DebuggerSession

  • روش

    رشته

  • پارامترها

    شیء اختیاری