browser.debugger

Deskripsi

Izin

Anda harus mendeklarasikan izin "debugger" dalam manifes ekstensi untuk menggunakan API ini.

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

Pembatasan kebijakan Enterprise

Di perangkat perusahaan, beberapa kebijakan dapat membatasi ekstensi agar tidak melampirkan debugger menggunakan model semua atau tidak sama sekali pada waktu lampiran (browser.debugger.attach()):

• Batasan host: Jika kebijakan perusahaan ExtensionSettings mengonfigurasi host yang diblokir (runtime_blocked_hosts) untuk ekstensi, browser.debugger.attach() akan diblokir di semua target dengan error "Host access is restricted by policy." (meskipun setiap origin ada di runtime_allowed_hosts).
• Kebijakan screenshot dan DLP: Jika kebijakan Enterprise DisableScreenshots menonaktifkan pengambilan screenshot atau aturan Pencegahan Kebocoran Data (DLP) berlaku untuk target, browser.debugger.attach() akan gagal dengan error "Screenshot capture is restricted by policy.".

Konsep dan penggunaan

Setelah dilampirkan, API browser.debugger memungkinkan Anda mengirim perintah Chrome DevTools Protocol (CDP) ke target tertentu. Penjelasan mendalam tentang CDP berada di luar cakupan dokumentasi ini. Untuk mempelajari CDP lebih lanjut, lihat dokumentasi CDP resmi.

Target

Target merepresentasikan sesuatu yang sedang di-debug—ini dapat mencakup tab, iframe, atau pekerja. Setiap target diidentifikasi oleh UUID dan memiliki jenis terkait (seperti iframe, shared_worker, dan lainnya).

Dalam target, mungkin ada beberapa konteks eksekusi—misalnya, iframe proses yang sama tidak mendapatkan target unik, tetapi ditampilkan sebagai konteks berbeda yang dapat diakses dari satu target.

Domain yang dibatasi

Untuk alasan keamanan, browser.debugger API tidak memberikan akses ke semua Domain Protokol Chrome DevTools. Domain yang tersedia adalah: Aksesibilitas, Audit, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulasi, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio, dan WebAuthn.

Bekerja dengan frame

Tidak ada pemetaan frame ke target satu per satu. Dalam satu tab, beberapa frame proses yang sama dapat berbagi target yang sama, tetapi menggunakan konteks eksekusi yang berbeda. Di sisi lain, target baru dapat dibuat untuk iframe di luar proses.

Untuk melampirkan ke semua frame, Anda harus menangani setiap jenis frame secara terpisah:

• Dengarkan peristiwa Runtime.executionContextCreated untuk mengidentifikasi konteks eksekusi baru yang terkait dengan frame proses yang sama.

• Ikuti langkah-langkah untuk melampirkan ke target terkait guna mengidentifikasi frame di luar proses.

Lampirkan ke target terkait

Setelah terhubung ke target, Anda dapat terhubung ke target terkait lainnya, termasuk frame turunan di luar proses atau pekerja terkait.

Mulai Chrome 125, browser.debugger API mendukung sesi datar. Hal ini memungkinkan Anda menambahkan target tambahan sebagai turunan ke sesi debugger utama dan mengirim pesan kepada mereka tanpa memerlukan panggilan lain ke browser.debugger.attach. Sebagai gantinya, Anda dapat menambahkan properti sessionId saat memanggil browser.debugger.sendCommand untuk mengidentifikasi target turunan yang ingin Anda kirimi perintah.

Untuk melampirkan secara otomatis ke frame turunan di luar proses, tambahkan terlebih dahulu pemroses untuk peristiwa 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");
  }
});

Kemudian, aktifkan auto attach dengan mengirim perintah Target.setAutoAttach dengan opsi flatten yang ditetapkan ke true:

await browser.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

Penyambungan otomatis hanya menyambungkan ke frame yang diketahui target, yang terbatas pada frame yang merupakan turunan langsung dari frame yang terkait dengannya. Misalnya, dengan hierarki frame A -> B -> C (yang semuanya lintas origin), memanggil Target.setAutoAttach untuk target yang terkait dengan A akan menyebabkan sesi juga dilampirkan ke B. Namun, tindakan ini tidak bersifat rekursif, jadi Target.setAutoAttach juga perlu dipanggil untuk B agar dapat melampirkan sesi ke C.

Contoh

Untuk mencoba API ini, instal contoh API debugger dari repositori 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,
)