chrome.debugger

Deskripsi

Izin

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

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

Pembatasan kebijakan perusahaan

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

• Pembatasan host: Jika kebijakan perusahaan ExtensionSettings mengonfigurasi host yang diblokir (runtime_blocked_hosts) untuk ekstensi, chrome.debugger.attach() akan diblokir di semua target dengan error "Host access is restricted by policy." (mesalipun asal individual berada di runtime_allowed_hosts).
• Kebijakan screenshot dan DLP: Jika kebijakan perusahaan DisableScreenshots menonaktifkan pengambilan screenshot atau aturan Pencegahan Kebocoran Data (DLP) berlaku untuk target, chrome.debugger.attach() akan gagal dengan error "Screenshot capture is restricted by policy.".

Konsep dan penggunaan

Setelah dilampirkan, chrome.debugger API 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 mewakili sesuatu yang sedang di-debug—hal 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 diwakili sebagai konteks berbeda yang dapat diakses dari satu target.

Domain yang dibatasi

Karena alasan keamanan, chrome.debugger API tidak memberikan akses ke semua Domain Chrome DevTools Protocol. Domain yang tersedia adalah: 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, 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.

Melampirkan ke target terkait

Setelah terhubung ke target, Anda mungkin ingin terhubung ke target terkait lebih lanjut, termasuk frame turunan di luar proses atau pekerja terkait.

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

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

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

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

Lampiran otomatis hanya melampirkan 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 (dengan semua lintas origin), memanggil Target.setAutoAttach untuk target yang terkait dengan A akan menyebabkan sesi juga dilampirkan ke B. Namun, hal ini tidak bersifat rekursif, sehingga Target.setAutoAttach juga perlu dipanggil untuk B guna 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,
)