browser.debugger

Deskripsi

chrome.debugger API berfungsi sebagai transport alternatif untuk protokol proses debug jarak jauh Chrome. Gunakan chrome.debugger untuk melampirkan ke satu atau beberapa tab guna menginstrumentasikan interaksi jaringan, men-debug JavaScript, mengubah DOM dan CSS, dan lainnya. Gunakan properti Debuggee tabId untuk menargetkan tab dengan sendCommand dan mengarahkan peristiwa menurut tabId dari callback onEvent.

Izin

debugger

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 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 origin individual ada di runtime_allowed_hosts).
  • Kebijakan screenshot dan DLP: Jika kebijakan perusahaan 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, browser.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 resmi CDP.

Target

Target merepresentasikan sesuatu yang sedang di-debug—ini dapat mencakup tab, iframe, atau worker. 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 direpresentasikan sebagai konteks berbeda yang dapat diakses dari satu target.

Domain yang dibatasi

Demi alasan keamanan, browser.debugger API tidak menyediakan akses ke semua Domain Protokol Chrome DevTools. Domain yang tersedia adalah: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Runtime, Storage, Target, Tracing, WebAudio, dan WebAuthn.

Bekerja dengan frame

Tidak ada pemetaan satu per satu antara frame dan target. Dalam satu tab, beberapa frame proses yang sama dapat menggunakan 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:

  • Proses 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.

Setelah terhubung ke target, Anda mungkin ingin terhubung ke target terkait lainnya, termasuk frame turunan di luar proses atau worker 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 target tersebut tanpa perlu melakukan 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 otomatis melampirkan ke frame turunan di luar proses, tambahkan pemroses terlebih dahulu 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 lampirkan otomatis dengan mengirimkan 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 }]
});

Lampirkan 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, ini tidak bersifat rekursif, sehingga Target.setAutoAttach juga perlu dipanggil agar B dapat menghubungkan sesi ke C.

Contoh

Untuk mencoba API ini, instal contoh debugger API dari repositori chrome-extension-samples.

Jenis

Debuggee

ID debuggee. tabId, extensionId, atau targetId harus ditentukan

Properti

  • extensionId

    string opsional

    ID ekstensi yang ingin Anda debug. Melampirkan ke halaman latar belakang ekstensi hanya dapat dilakukan jika tombol command line --silent-debugger-extension-api digunakan.

  • tabId

    number opsional

    ID tab yang ingin Anda debug.

  • targetId

    string opsional

    ID buram target debug.

DebuggerSession

Chrome 125+ browser.* sejak Chrome 148

ID sesi debugger. Salah satu dari tabId, extensionId, atau targetId harus ditentukan. Selain itu, sessionId opsional dapat diberikan. Jika sessionId ditentukan untuk argumen yang dikirim dari onEvent, berarti peristiwa tersebut berasal dari sesi protokol turunan dalam sesi debuggee root. Jika sessionId ditentukan saat diteruskan ke sendCommand, sessionId akan menargetkan sesi protokol turunan dalam sesi debuggee root.

Properti

  • extensionId

    string opsional

    ID ekstensi yang ingin Anda debug. Melampirkan ke halaman latar belakang ekstensi hanya dapat dilakukan jika tombol command line --silent-debugger-extension-api digunakan.

  • sessionId

    string opsional

    ID buram sesi Chrome DevTools Protocol. Mengidentifikasi sesi turunan dalam sesi root yang diidentifikasi oleh tabId, extensionId, atau targetId.

  • tabId

    number opsional

    ID tab yang ingin Anda debug.

  • targetId

    string opsional

    ID buram target debug.

DetachReason

Chrome 44+ browser.* sejak Chrome 148

Alasan penghentian koneksi.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informasi target debug

Properti

  • terpasang

    boolean

    True jika debugger sudah terpasang.

  • extensionId

    string opsional

    ID ekstensi, ditentukan jika type = 'background_page'.

  • faviconUrl

    string opsional

    URL favicon target.

  • id

    string

    ID target.

  • tabId

    number opsional

    ID tab, ditentukan jika type == 'page'.

  • judul

    string

    Judul halaman target.

  • Jenis target.

  • url

    string

    URL target.

TargetInfoType

Chrome 44+ browser.* sejak Chrome 148

Jenis target.

Enum

"page"

"background_page"

"worker"

"other"

Metode

attach()

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

Memasang debugger ke target yang diberikan.

Parameter

  • target

    Debuggee

    Target proses debug yang ingin Anda lampirkan.

  • requiredVersion

    string

    Versi protokol proses debug yang diperlukan ("0.1"). Seseorang hanya dapat melampirkan ke debuggee dengan versi utama yang cocok dan versi minor yang lebih besar atau sama. Daftar versi protokol dapat diperoleh di sini.

Hasil

  • Promise<void>

    Chrome 96+ browser.* sejak Chrome 148

    Diselesaikan setelah operasi lampiran berhasil atau gagal. Promise akan di-resolve tanpa nilai. Jika lampiran gagal, promise akan ditolak.

detach()

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

Melepas debugger dari target yang diberikan.

Parameter

  • target

    Debuggee

    Target proses debug yang ingin Anda lepaskan.

Hasil

  • Promise<void>

    Chrome 96+ browser.* sejak Chrome 148

    Diselesaikan setelah operasi pelepasan berhasil atau gagal. Promise akan di-resolve tanpa nilai. Jika pelepasan gagal, promise akan ditolak.

getTargets()

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

Menampilkan daftar target debug yang tersedia.

Hasil

  • Promise<TargetInfo[]>

    Chrome 96+ browser.* sejak Chrome 148

sendCommand()

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

Mengirim perintah yang diberikan ke target proses debug.

Parameter

  • Target proses debug yang ingin Anda kirimi perintah.

  • metode

    string

    Nama metode. Harus berupa salah satu metode yang ditentukan oleh protokol proses debug jarak jauh.

  • commandParams

    objek opsional

    Objek JSON dengan parameter permintaan. Objek ini harus sesuai dengan skema parameter proses debug jarak jauh untuk metode tertentu.

Hasil

  • Promise<object | undefined>

    Chrome 96+ browser.* sejak Chrome 148

    Isi respons. Jika terjadi error saat memposting pesan, promise akan ditolak.

Acara

onDetach

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

Diaktifkan saat browser menghentikan sesi proses debug untuk tab. Hal ini terjadi saat tab ditutup atau Chrome DevTools dipanggil untuk tab yang terpasang.

Parameter

onEvent

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

Diaktifkan setiap kali target proses debug mengeluarkan peristiwa instrumentasi.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

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