browser.debugger

Opis

Interfejs chrome.debugger API służy jako alternatywny transport dla protokołu zdalnego debugowania Chrome. Użyj chrome.debugger, aby dołączyć do co najmniej 1 karty i instrumentować interakcje sieciowe, debugować JavaScript, zmieniać DOM i CSS oraz wykonywać inne czynności. Użyj właściwości Debuggee tabId, aby kierować zdarzenia na karty z wartością sendCommand i kierować zdarzenia według wartości 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 zasad organizacji

Na urządzeniach firmowych niektóre zasady mogą ograniczać możliwość dołączania debugera przez rozszerzenia za pomocą modelu „wszystko albo nic” w momencie dołączania (browser.debugger.attach()):

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

Pojęcia i zastosowanie

Po dołączeniu browser.debugger interfejs API umożliwia wysyłanie poleceń protokołu narzędzi deweloperskich w Chrome (CDP) do danego miejsca docelowego. Szczegółowe wyjaśnienie działania platformy CDP wykracza poza zakres tej dokumentacji. Więcej informacji o CDP znajdziesz w oficjalnej dokumentacji.

Cele

Obiekty docelowe reprezentują coś, co jest debugowane – może to być karta, element iframe lub proces roboczy. Każdy element docelowy jest identyfikowany przez UUID i ma powiązany typ (np. iframe, shared_worker itp.).

W ramach jednego celu może występować wiele kontekstów wykonania. Na przykład ramki iframe w tym samym procesie nie otrzymują unikalnego celu, ale są reprezentowane jako różne konteksty, do których można uzyskać dostęp z pojedynczego celu.

Domeny z ograniczeniami

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

Praca z ramkami

Nie ma mapowania 1:1 klatek na cele. W ramach jednej karty kilka ramek tego samego procesu może mieć ten sam cel, ale używać innego kontekstu wykonania. Z drugiej strony w przypadku ramki iframe działającej w innym procesie można utworzyć nowy cel.

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

  • Nasłuchuj zdarzenia Runtime.executionContextCreated, aby identyfikować nowe konteksty wykonania powiązane z tymi samymi ramkami 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 kolejnymi powiązanymi elementami docelowymi, w tym z ramkami podrzędnymi działającymi poza procesem lub powiązanymi procesami roboczymi.

Od Chrome 125 interfejs browser.debugger API obsługuje sesje płaskie. Dzięki temu możesz dodawać dodatkowe cele jako elementy podrzędne do głównej sesji debugera i wysyłać do nich wiadomości bez konieczności wykonywania kolejnego wywołania funkcji browser.debugger.attach. Zamiast tego możesz dodać właściwość sessionId podczas wywoływania funkcji browser.debugger.sendCommand, aby określić urządzenie docelowe dziecka, do którego chcesz wysłać polecenie.

Aby automatycznie dołączać do ramek podrzędnych działających w innym procesie, 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 działa tylko w przypadku ramek, o których wie element docelowy, czyli ramek, które są bezpośrednimi elementami podrzędnymi ramki powiązanej z tym elementem. Na przykład w hierarchii ramek A –> B –> C (gdzie wszystkie są współdzielone) wywołanie Target.setAutoAttach w przypadku elementu docelowego powiązanego z ramką A spowoduje, że sesja zostanie też dołączona do ramki B. Nie jest to jednak rekurencyjne, więc w przypadku B należy też wywołać Target.setAutoAttach, 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 obiektu. Należy określić tabId, extensionId lub targetId

Właściwości

  • extensionId

    ciąg znaków opcjonalny

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

  • tabId

    number opcjonalny

    Identyfikator karty, którą chcesz debugować.

  • targetId

    ciąg znaków opcjonalny

    Nieprzezroczysty identyfikator celu debugowania.

DebuggerSession

Chrome 125 lub nowsza

Identyfikator sesji debugera. Musisz podać jeden z tych identyfikatorów: tabId, extensionId lub targetId. Dodatkowo można podać opcjonalny identyfikator sesji. Jeśli w przypadku argumentów wysyłanych z onEvent określono sessionId, oznacza to, że zdarzenie pochodzi z sesji protokołu podrzędnego w sesji głównej debugowanego procesu. Jeśli identyfikator sesji jest określony podczas przekazywania do sendCommand, jest on kierowany do sesji protokołu podrzędnego w sesji debugowania głównego.

Właściwości

  • extensionId

    ciąg znaków opcjonalny

    Identyfikator rozszerzenia, które chcesz debugować. Dołączanie do strony tła rozszerzenia 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. Wskazuje sesję podrzędną w sesji głównej zidentyfikowanej przez tabId, extensionId lub targetId.

  • tabId

    number opcjonalny

    Identyfikator karty, którą chcesz debugować.

  • targetId

    ciąg znaków opcjonalny

    Nieprzezroczysty identyfikator celu debugowania.

DetachReason

Chrome 44 lub nowszy

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

    Wartość 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 miejsca docelowego.

  • tabId

    number opcjonalny

    Identyfikator karty, zdefiniowany, jeśli typ == „page”.

  • tytuł

    tekst

    Tytuł strony docelowej.

  • Typ celu.

  • URL

    tekst

    Docelowy adres URL.

TargetInfoType

Chrome 44 lub nowszy

Typ celu.

Typ wyliczeniowy

„page”

"background_page"

„worker”

„other”

Metody

attach()

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

Dołącza debuger do danego elementu docelowego.

Parametry

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

  • requiredVersion

    tekst

    Wymagana wersja protokołu debugowania („0.1”). Do debugowanego programu można dołączyć tylko debuger o pasującej wersji głównej i wersji podrzędnej równej lub nowszej. Listę wersji protokołu znajdziesz tutaj.

Zwroty

  • Promise<void>

    Chrome 96 lub nowsza

    Zwraca obietnicę po zakończeniu operacji dołączania (powodzeniem lub niepowodzeniem). Obietnica jest spełniona bez wartości. Jeśli dołączenie się nie powiedzie, obietnica zostanie odrzucona.

detach()

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

Odłącza debuger od danego miejsca docelowego.

Parametry

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

Zwroty

  • Promise<void>

    Chrome 96 lub nowsza

    Zwraca obietnicę po zakończeniu operacji odłączania (powodzeniem lub niepowodzeniem). Obietnica jest spełniona bez wartości. Jeśli odłączenie się nie powiedzie, obietnica zostanie odrzucona.

getTargets()

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

Zwraca listę dostępnych celów debugowania.

Zwroty

sendCommand()

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

    obiekt opcjonalny

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

Zwroty

  • Promise<object | undefined>

    Chrome 96 lub nowsza

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

Wydarzenia

onDetach

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

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

Parametry

onEvent

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

Uruchamiane za każdym razem, gdy zdarzenie instrumentacji zgłasza problemy z elementem docelowym debugowania.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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