chrome.debugger

Deskripsi

chrome.debugger API berfungsi sebagai transpor alternatif untuk protokol proses debug jarak jauh Chrome. Gunakan chrome.debugger untuk melampirkan ke satu atau beberapa tab untuk menginstrumentasikan interaksi jaringan, men-debug JavaScript, memutar DOM dan CSS, dan lainnya. Gunakan properti Debuggee tabId untuk menargetkan tab dengan sendCommand dan merutekan 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",
  ],
  ...
}

Konsep dan penggunaan

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

Target

Target mewakili 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 direpresentasikan sebagai konteks yang berbeda yang dapat diakses dari satu target.

Domain yang dibatasi

Untuk alasan keamanan, chrome.debugger API tidak memberikan akses ke semua Domain Protokol Chrome DevTools. Domain yang tersedia adalah: Aksesibilitas, Audit, CacheStorage, Konsol, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulasi, Fetch, IO, Input, Inspector, Log, Jaringan, Overlay, Halaman, Performa, Profiler, Runtime, Penyimpanan, Target, Pelacakan, WebAudio, dan WebAuthn.

Menangani frame

Tidak ada pemetaan satu per satu dari frame ke target. Dalam satu tab, beberapa frame proses yang sama dapat memiliki 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 perlu 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.

Setelah terhubung ke target, Anda dapat 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 kepada mereka 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 kirim perintah.

Untuk secara otomatis melampirkan ke frame turunan di luar proses, tambahkan pemroses untuk peristiwa Target.attachedToTarget terlebih dahulu:

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 lampirkan otomatis dengan mengirimkan perintah Target.setAutoAttach dengan opsi flatten ditetapkan ke true:

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

Lampiran otomatis hanya dilampirkan ke frame yang diketahui target, yang dibatasi untuk frame yang merupakan turunan langsung dari frame yang terkait dengannya. Misalnya, dengan hierarki frame A -> B -> C (dengan semua bersifat lintas-asal), 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 melampirkan 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. Lampiran 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+

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, artinya peristiwa 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. Lampiran ke halaman latar belakang ekstensi hanya dapat dilakukan jika tombol command line --silent-debugger-extension-api digunakan.

  • sessionId

    string opsional

    ID buram sesi Protokol Chrome DevTools. 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+

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, yang ditentukan jika jenis = 'background_page'.

  • faviconUrl

    string opsional

    URL favicon target.

  • id

    string

    ID target.

  • tabId

    number opsional

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

  • judul

    string

    Judul halaman target.

  • Jenis target.

  • url

    string

    URL Target.

TargetInfoType

Chrome 44+

Jenis target.

Enum

"page"

"background_page"

"worker"

"other"

Metode

attach()

Promise 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

Melampirkan 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"). Anda 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.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    () => void

Hasil

  • Promise<void>

    Chrome 96+

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

detach()

Promise 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

Melepas debugger dari target yang diberikan.

Parameter

  • target

    Debuggee

    Target proses debug yang ingin Anda lepaskan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    () => void

Hasil

  • Promise<void>

    Chrome 96+

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getTargets()

Promise 
chrome.debugger.getTargets(
  callback?: function,
)

Menampilkan daftar target debug yang tersedia.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (result: TargetInfo[]) => void

    • hasil

      TargetInfo[]

      Array objek TargetInfo yang sesuai dengan target debug yang tersedia.

Hasil

  • Promise<TargetInfo[]>

    Chrome 96+

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

sendCommand()

Promise 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

Mengirim perintah yang diberikan ke target proses debug.

Parameter

  • Target proses debug yang ingin Anda kirimkan perintah.

  • method

    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.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (result?: object) => void

    • hasil

      objek opsional

      Objek JSON dengan respons. Struktur respons bervariasi bergantung pada nama metode dan ditentukan oleh atribut 'returns' dari deskripsi perintah dalam protokol proses debug jarak jauh.

Hasil

  • Promise<object | undefined>

    Chrome 96+

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

Acara

onDetach

chrome.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 dilampirkan.

Parameter

onEvent

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

Diaktifkan setiap kali men-debug target yang mengeluarkan peristiwa instrumentasi.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

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