browser.debugger

Beschrijving

De chrome.debugger API dient als alternatief transport voor het protocol voor externe foutopsporing van Chrome. Gebruik chrome.debugger om aan een of meer tabbladen te koppelen om onder andere netwerkinteractie te instrumenteren, JavaScript te debuggen en de DOM en CSS te muteren. Gebruik de property Debuggee tabId om tabbladen te targeten met sendCommand en gebeurtenissen te routeren op tabId vanuit onEvent-callbacks.

Rechten

debugger

Je moet het recht "debugger" definiëren in het manifest van je extensie om deze API te gebruiken.

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

Beperkingen voor bedrijfsbeleid

Op bedrijfsapparaten kunnen sommige beleidsregels voorkomen dat extensies de debugger koppelen via een alles-of-niets-model op het moment van koppelen (browser.debugger.attach()):

  • Hostbeperkingen: Als het bedrijfsbeleid ExtensionSettings geblokkeerde hosts (runtime_blocked_hosts) instelt voor een extensie, wordt browser.debugger.attach() geblokkeerd op alle doelen met de foutmelding "Host access is restricted by policy." (zelfs als afzonderlijke oorsprongen in runtime_allowed_hosts staan).
  • Beleid voor screenshots en DLP: Als het bedrijfsbeleid DisableScreenshots het maken van screenshots uitzet of als er regels voor gegevensverlies voorkomen (DLP) van toepassing zijn op het doel, mislukt browser.debugger.attach() met de foutmelding "Screenshot capture is restricted by policy.".

Concepten en gebruik

Nadat je de browser.debugger API hebt gekoppeld, kun je opdrachten van het Chrome DevTools-protocol (CDP) naar een bepaald doel sturen. Een uitgebreide uitleg van het CDP valt buiten het bereik van deze documentatie. Ga naar de officiële CDP-documentatie voor meer informatie over het CDP.

Doelen

Doelen vertegenwoordigen iets dat wordt gedebugd. Dit kan een tabblad, een iframe of een worker zijn. Elk doel wordt geïdentificeerd door een UUID en heeft een bijbehorend type (zoals iframe, shared_worker en meer).

Binnen een doel kunnen er meerdere uitvoeringscontexten zijn, bijvoorbeeld: iframes van hetzelfde proces krijgen geen uniek doel, maar worden vertegenwoordigd als verschillende contexten die toegankelijk zijn vanuit één doel.

Beperkte domeinen

Om veiligheidsredenen biedt de browser.debugger-API geen toegang tot alle domeinen van het Chrome DevTools-protocol. De beschikbare domeinen zijn: 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 en WebAuthn.

Werken met frames

Er is geen een-op-een-toewijzing van frames aan doelen. Binnen één tabblad kunnen meerdere frames van hetzelfde proces hetzelfde doel delen, maar een andere uitvoeringscontext gebruiken. Aan de andere kant kan er een nieuw doel worden gemaakt voor een out-of-process iframe.

Als je aan alle frames wilt koppelen, moet je elk type frame afzonderlijk verwerken:

  • Luister naar de gebeurtenis Runtime.executionContextCreated om nieuwe uitvoeringscontexten te identificeren die zijn gekoppeld aan dezelfde procesframes.

  • Volg de stappen om te koppelen aan gerelateerde doelen om frames buiten het proces te identificeren.

Nadat je verbinding hebt gemaakt met een doel, wil je misschien verbinding maken met andere gerelateerde doelen, waaronder onderliggende frames buiten het proces of bijbehorende workers.

Vanaf Chrome 125 ondersteunt de browser.debugger API platte sessies. Hiermee kun je extra doelen als onderliggende elementen toevoegen aan je hoofd-debuggersessie en ze berichten sturen zonder dat je nog een aanroep naar browser.debugger.attach nodig hebt. In plaats daarvan kun je een sessionId-property toevoegen als je browser.debugger.sendCommand aanroept om het onderliggende doel te identificeren waarnaar je een opdracht wilt sturen.

Als je automatisch wilt koppelen aan onderliggende frames buiten het proces, voeg je eerst een listener toe voor de gebeurtenis 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");
  }
});

Zet daarna automatisch bijvoegen aan door de opdracht Target.setAutoAttach te sturen met de optie flatten ingesteld op true:

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

Automatisch bijvoegen voegt alleen bij aan frames waarvan het doel op de hoogte is. Dit is beperkt tot frames die directe onderliggende elementen zijn van een frame dat eraan is gekoppeld. Bijvoorbeeld: met de framehiërarchie A -> B -> C (waarbij alle cross-origin zijn), leidt het aanroepen van Target.setAutoAttach voor het doel dat aan A is gekoppeld ertoe dat de sessie ook aan B wordt gekoppeld. Dit is echter niet recursief, dus Target.setAutoAttach moet ook worden aangeroepen voor B om de sessie aan C te koppelen.

Voorbeelden

Als je deze API wilt proberen, installeer je het voorbeeld van de debugger-API uit de repository chrome-extension-samples.

Typen

Debuggee

ID van debuggee. tabId, extensionId of targetId moet worden ingevoerd

Eigenschappen

  • extensionId

    tekenreeks optioneel

    De ID van de extensie die je wilt debuggen. Koppelen aan een achtergrondpagina van een extensie is alleen mogelijk als de opdrachtregeloptie --silent-debugger-extension-api wordt gebruikt.

  • tabId

    number optioneel

    De ID van het tabblad dat je wilt debuggen.

  • targetId

    tekenreeks optioneel

    De ondoorzichtige ID van het foutopsporingsdoel.

DebuggerSession

Chrome 125+ browser.* sinds Chrome 148

ID van de foutopsporingssessie. Er moet een tabId, extensionId of targetId worden ingevoerd. Daarnaast kan een optionele sessionId worden verstrekt. Als sessionId is ingevoerd voor argumenten die worden gestuurd vanuit onEvent, betekent dit dat de gebeurtenis afkomstig is van een onderliggende protocolsessie binnen de root-debuggee-sessie. Als sessionId wordt gespecificeerd wanneer deze wordt doorgegeven aan sendCommand, is deze gericht op een onderliggende protocolsessie binnen de root-debuggee-sessie.

Eigenschappen

  • extensionId

    tekenreeks optioneel

    De ID van de extensie die je wilt debuggen. Koppelen aan een achtergrondpagina van een extensie is alleen mogelijk als de opdrachtregeloptie --silent-debugger-extension-api wordt gebruikt.

  • sessionId

    tekenreeks optioneel

    De ondoorzichtige ID van de sessie van het Chrome DevTools-protocol. Identificeert een onderliggende sessie binnen de hoofdsessie die wordt geïdentificeerd door tabId, extensionId of targetId.

  • tabId

    number optioneel

    De ID van het tabblad dat je wilt debuggen.

  • targetId

    tekenreeks optioneel

    De ondoorzichtige ID van het foutopsporingsdoel.

DetachReason

Chrome 44+ browser.* sinds Chrome 148

Reden voor beëindiging van de verbinding.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informatie over foutopsporingsdoel

Eigenschappen

  • gekoppeld

    booleaans

    True als de debugger al is gekoppeld.

  • extensionId

    tekenreeks optioneel

    De extensie-ID, gedefinieerd als type = 'background_page'.

  • faviconUrl

    tekenreeks optioneel

    Doelfavicon-URL.

  • id

    tekenreeks

    Doel-ID.

  • tabId

    number optioneel

    De tabblad-ID, gedefinieerd als type == 'page'.

  • titel

    tekenreeks

    Titel van doelpagina.

  • Doeltype.

  • url

    tekenreeks

    Doel-URL.

TargetInfoType

Chrome 44+ browser.* sinds Chrome 148

Doeltype.

Enum

"page"

"background_page"

"worker"

"other"

Methoden

attach()

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

Koppelt de debugger aan het opgegeven doel.

Parameters

  • target

    Debuggee

    Het foutopsporingsdoel waaraan je wilt koppelen.

  • requiredVersion

    tekenreeks

    Vereiste versie van foutopsporingsprotocol (0.1). Je kunt alleen koppelen aan de debuggee met een overeenkomende hoofdversie en een grotere of gelijke onderversie. Hier vindt u een lijst met de protocolversies.

Retourzendingen

  • Promise<void>

    Chrome 96+ browser.* sinds Chrome 148

    Wordt opgelost zodra de koppelingsbewerking is geslaagd of mislukt. De belofte wordt omgezet zonder waarde. Als de koppeling mislukt, wordt de promise afgewezen.

detach()

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

Maakt de debugger los van het opgegeven doel.

Parameters

  • target

    Debuggee

    Het foutopsporingsdoel waarvan je de koppeling wilt verwijderen.

Retourzendingen

  • Promise<void>

    Chrome 96+ browser.* sinds Chrome 148

    Wordt opgelost zodra de ontkoppelingsbewerking is geslaagd of mislukt. De belofte wordt omgezet zonder waarde. Als het loskoppelen mislukt, wordt de promise afgewezen.

getTargets()

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

Retourneert de lijst met beschikbare foutopsporingsdoelen.

Retourzendingen

  • Promise<TargetInfo[]>

    Chrome 96+ browser.* sinds Chrome 148

sendCommand()

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

Stuurt de gegeven opdracht naar het foutopsporingsdoel.

Parameters

  • Het foutopsporingsdoel waarnaar je de opdracht wilt sturen.

  • method

    tekenreeks

    Methodenaam. Moet een van de methoden zijn die zijn gedefinieerd door het protocol voor foutopsporing op afstand.

  • commandParams

    object optioneel

    Json-object met verzoekparameters. Dit object moet voldoen aan het schema voor parameters voor foutopsporing op afstand voor de gegeven methode.

Retourzendingen

  • Promise<object | undefined>

    Chrome 96+ browser.* sinds Chrome 148

    Tekstgedeelte van reactie. Als er een fout optreedt bij het posten van het bericht, wordt de promise afgewezen.

Evenementen

onDetach

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

Wordt geactiveerd als de browser de foutopsporingssessie voor het tabblad beëindigt. Dit gebeurt als het tabblad wordt gesloten of als Chrome DevTools wordt aangeroepen voor het bijgevoegde tabblad.

Parameters

onEvent

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

Wordt geactiveerd wanneer het foutopsporingsdoel een instrumentatiegebeurtenis uitvoert.

Parameters

  • callback

    functie

    De parameter callback ziet er zo uit: 

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