browser.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 باشد).
• خط‌مشی‌های «جلوگیری از ازدست رفتن داده‌ها» و نماگرفت: اگر خط‌مشی سازمانی DisableScreenshots ضبط نماگرفت را غیرفعال کند یا قوانین «جلوگیری از ازدست رفتن داده‌ها» (DLP) برای هدف اعمال شود، browser.debugger.attach() با خطای "Screenshot capture is restricted by policy." ناموفق خواهد بود.

مفاهیم و استفاده

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

هدف‌ها

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

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

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

به‌دلایل امنیتی، «میانای برنامه‌سازی کاربردی» browser.debugger دسترسی به همه «حوزه‌های پروتکل» Chrome DevTools را فراهم نمی‌کند. دامنه‌های دردسترس عبارت‌اند از: دسترسی‌پذیری، ممیزی‌ها، 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 از جلسه‌های مسطح پشتیبانی می‌کند. این به شما امکان می‌دهد هدف‌های بیشتری را به‌عنوان فرزند به جلسه اشکال‌زدایی اصلی‌تان اضافه کنید و بدون نیاز به فراخوانی دیگری به 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 نصب کنید.

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

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

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

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

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

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