browser.debugger

Opis

Interfejs API chrome.debugger służy jako alternatywny transport dla protokołu zdalnego debugowania w Chrome. Użyj chrome.debugger, aby dołączyć do co najmniej jednej karty i instrumentować interakcje sieciowe, debugować JavaScript, mutować DOM i CSS oraz wykonywać inne czynności. Użyj właściwości Debuggee tabId, aby kierować karty za pomocą sendCommand i kierować zdarzenia według tabId z wywołań zwrotnych onEvent.

Uprawnienia

debugger

Aby korzystać z tego interfejsu API, musisz zadeklarować uprawnienie "debugger" w pliku manifestu rozszerzenia.

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

Ograniczenia wynikające z zasad przedsiębiorstwa

Na urządzeniach firmowych niektóre zasady mogą uniemożliwiać rozszerzeniom dołączanie debugera przy użyciu modelu „wszystko albo nic” w momencie dołączania (browser.debugger.attach()):

  • Ograniczenia dotyczące hostów: jeśli zasada przedsiębiorstwa ExtensionSettings konfiguruje zablokowane hosty (runtime_blocked_hosts) dla rozszerzenia, interfejs browser.debugger.attach() jest blokowany we wszystkich miejscach docelowych i wyświetla się błąd "Host access is restricted by policy." (nawet jeśli poszczególne źródła są w runtime_allowed_hosts).
  • Zasady dotyczące zrzutów ekranu i zapobiegania utracie danych (DLP): jeśli zasada firmowa DisableScreenshots wyłącza robienie zrzutów ekranu lub do celu mają zastosowanie reguły zapobiegania utracie danych (DLP), metoda browser.debugger.attach() kończy się błędem "Screenshot capture is restricted by policy.".

Pojęcia i użycie

Po dołączeniu interfejs API browser.debugger umożliwia wysyłanie poleceń protokołu Narzędzi deweloperskich w Chrome (CDP) do określonego celu. Szczegółowe wyjaśnienie CDP wykracza poza zakres tej dokumentacji. Aby dowiedzieć się więcej o CDP, zapoznaj się z oficjalną dokumentacją CDP.

Cele

Cele reprezentują elementy, które są debugowane – może to być karta, element iframe lub skrypt service worker. Każdy cel jest identyfikowany przez identyfikator UUID i ma powiązany typ (np. iframe, shared_worker i inne).

W ramach celu może istnieć wiele kontekstów wykonywania – na przykład elementy iframe tego samego procesu nie otrzymują unikalnego celu, ale są reprezentowane jako różne konteksty, do których można uzyskać dostęp z jednego celu.

Domeny z ograniczeniami

Ze względów bezpieczeństwa interfejs API browser.debugger nie zapewnia dostępu do wszystkich domen protokołu Narzędzi deweloperskich w Chrome. Dostępne domeny: 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 i WebAuthn.

Praca z ramkami

Nie ma mapowania klatek na cele w stosunku 1:1. Na jednej karcie wiele ramek tego samego procesu może mieć ten sam cel, ale używać innego kontekstu wykonywania. Z drugiej strony dla elementu iframe poza procesem może zostać utworzony nowy cel.

Aby dołączyć do wszystkich ramek, musisz obsłużyć każdy typ ramki osobno:

  • Nasłuchuj zdarzenia Runtime.executionContextCreated, aby identyfikować nowe konteksty wykonywania powiązane z ramkami tego samego procesu.

  • Aby zidentyfikować ramki poza procesem, wykonaj czynności opisane w sekcji Dołączanie do powiązanych elementów docelowych.

Po połączeniu z elementem docelowym możesz połączyć się z innymi powiązanymi elementami docelowymi, w tym z ramkami podrzędnymi poza procesem lub powiązanymi skryptami service worker.

Od Chrome 125 interfejs API browser.debugger obsługuje sesje płaskie. Dzięki temu możesz dodawać kolejne cele jako elementy podrzędne do głównej sesji debugera i wysyłać do nich wiadomości bez konieczności ponownego wywoływania metody browser.debugger.attach. Zamiast tego możesz dodać właściwość sessionId podczas wywoływania browser.debugger.sendCommand, aby zidentyfikować element podrzędny, do którego chcesz wysłać polecenie.

Aby automatycznie dołączać do ramek podrzędnych poza procesem, najpierw dodaj detektor zdarzenia 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");
  }
});

Następnie włącz automatyczne dołączanie, wysyłając polecenie Target.setAutoAttach z opcją flatten ustawioną na true:

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

Automatyczne dołączanie dotyczy tylko ramek, o których wie element docelowy, czyli ramek, które są bezpośrednimi elementami podrzędnymi powiązanej z nim ramki. Na przykład w hierarchii ramek A -> B -> C (gdzie wszystkie są współdzielone) wywołanie Target.setAutoAttach dla celu powiązanego z A spowoduje, że sesja zostanie dołączona również do B. Nie jest to jednak rekurencyjne, więc trzeba też wywołać Target.setAutoAttach dla B, aby dołączyć sesję do C.

Przykłady

Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu API debuggera z repozytorium chrome-extension-samples.

Typy

Debuggee

Identyfikator debugowanego elementu. Należy podać tabId, extensionId lub targetId

Właściwości

  • extensionId

    ciąg znaków opcjonalny

    Identyfikator rozszerzenia, które chcesz debugować. Dołączenie do strony rozszerzenia w tle jest możliwe tylko wtedy, gdy używany jest przełącznik wiersza poleceń --silent-debugger-extension-api.

  • tabId

    number optional

    Identyfikator karty, którą chcesz debugować.

  • targetId

    ciąg znaków opcjonalny

    Identyfikator celu debugowania.

DebuggerSession

Chrome 125 lub nowsza browser.* od Chrome 148

Identyfikator sesji debugera. Należy podać tabId, extensionId lub targetId. Dodatkowo można podać opcjonalny parametr sessionId. Jeśli sessionId jest określony dla argumentów wysyłanych z onEvent, oznacza to, że zdarzenie pochodzi z sesji protokołu podrzędnego w ramach sesji debugowania głównego. Jeśli identyfikator sessionId jest określony podczas przekazywania do sendCommand, jest on kierowany na sesję protokołu podrzędnego w ramach sesji debugowania głównego.

Właściwości

  • extensionId

    ciąg znaków opcjonalny

    Identyfikator rozszerzenia, które chcesz debugować. Dołączenie do strony rozszerzenia w tle jest możliwe tylko wtedy, gdy używany jest przełącznik wiersza poleceń --silent-debugger-extension-api.

  • sessionId

    ciąg znaków opcjonalny

    Nieprzejrzysty identyfikator sesji protokołu narzędzi deweloperskich w Chrome. Identyfikuje sesję podrzędną w sesji głównej identyfikowanej przez tabId, extensionId lub targetId.

  • tabId

    number optional

    Identyfikator karty, którą chcesz debugować.

  • targetId

    ciąg znaków opcjonalny

    Identyfikator celu debugowania.

DetachReason

Chrome 44 lub nowsza browser.* od Chrome 148

Przyczyna zakończenia połączenia.

Typ wyliczeniowy

"target_closed"

"canceled_by_user"

TargetInfo

Informacje o celu debugowania

Właściwości

  • podłączony

    wartość logiczna

    Prawda, jeśli debuger jest już dołączony.

  • extensionId

    ciąg znaków opcjonalny

    Identyfikator rozszerzenia, zdefiniowany, jeśli typ = „background_page”.

  • faviconUrl

    ciąg znaków opcjonalny

    Docelowy adres URL favikony.

  • id

    tekst

    Identyfikator elementu docelowego.

  • tabId

    number optional

    Identyfikator karty, zdefiniowany, jeśli type == 'page'.

  • tytuł

    tekst

    Tytuł strony docelowej.

  • Typ celu.

  • URL

    tekst

    Docelowy URL.

TargetInfoType

Chrome 44 lub nowsza browser.* od Chrome 148

Typ celu.

Typ wyliczeniowy

"page"

"background_page"

"worker"

"other"

Metody

attach()

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

Dołącza debuger do danego celu.

Parametry

  • cel

    Debuggee

    Cel debugowania, do którego chcesz dołączyć.

  • requiredVersion

    tekst

    Wymagana wersja protokołu debugowania („0.1”). Można dołączyć tylko do debugowanego programu z pasującą wersją główną i większą lub równą wersją podrzędną. Listę wersji protokołu znajdziesz tutaj.

Zwroty

  • thought Promise<void>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

    Rozwiązuje problem po powodzeniu lub niepowodzeniu operacji dołączania. Obietnica jest rozwiązywana bez wartości. Jeśli dołączenie się nie powiedzie, obietnica zostanie odrzucona.

detach()

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

Odłącza debuger od danego celu.

Parametry

  • cel

    Debuggee

    Cel debugowania, od którego chcesz się odłączyć.

Zwroty

  • thought Promise<void>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

    Rozwiązuje problem po powodzeniu lub niepowodzeniu operacji odłączenia. Obietnica jest rozwiązywana bez wartości. Jeśli odłączenie się nie powiedzie, obietnica zostanie odrzucona.

getTargets()

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

Zwraca listę dostępnych miejsc docelowych debugowania.

Zwroty

  • Promise<TargetInfo[]>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

sendCommand()

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

Wysyła podane polecenie do celu debugowania.

Parametry

  • Cel debugowania, do którego chcesz wysłać polecenie.

  • method

    tekst

    Nazwa metody. Powinna to być jedna z metod zdefiniowanych przez protokół zdalnego debugowania.

  • commandParams

    object opcjonalny

    Obiekt JSON z parametrami żądania. Ten obiekt musi być zgodny ze schematem parametrów zdalnego debugowania dla danej metody.

Zwroty

  • Promise<object | undefined>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

    Treść odpowiedzi. Jeśli podczas publikowania wiadomości wystąpi błąd, obietnica zostanie odrzucona.

Wydarzenia

onDetach

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

Uruchamiane, gdy przeglądarka kończy sesję debugowania karty. Dzieje się tak, gdy karta jest zamykana lub gdy narzędzia deweloperskie w Chrome są wywoływane na dołączonej karcie.

Parametry

onEvent

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

Uruchamiane za każdym razem, gdy zdarzenie instrumentacji debuguje problemy z elementem docelowym.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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