اشکال‌زدای مرورگر

توضیحات

مجوزها

برای استفاده از این API، باید مجوز "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." با شکست مواجه می‌شود.

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

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

اهداف

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

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

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

به دلایل امنیتی، API browser.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 گوش دهید تا زمینه‌های اجرایی جدید مرتبط با فریم‌های فرآیند مشابه را شناسایی کنید.

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

به اهداف مرتبط متصل شوید

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

از نسخه ۱۲۵ کروم، API browser.debugger از نشست‌های مسطح (flat sessions) پشتیبانی می‌کند. این به شما امکان می‌دهد تا اهداف اضافی را به عنوان فرزند به نشست اصلی اشکال‌زدای خود اضافه کنید و بدون نیاز به فراخوانی مجدد 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 (که همه آنها cross-origin هستند)، فراخوانی Target.setAutoAttach برای هدف مرتبط با A منجر به اتصال session به B نیز می‌شود. با این حال، این بازگشتی نیست، بنابراین Target.setAutoAttach نیز باید برای اتصال session به C فراخوانی شود.

مثال‌ها

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