browser.debugger

Beschrijving

De chrome.debugger API dient als alternatief transport voor het protocol voor foutopsporing op afstand van Chrome. Gebruik chrome.debugger om aan een of meer tabbladen te koppelen om netwerkinteractie te instrumenteren, JavaScript te debuggen, het DOM en CSS te muteren en meer. 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 kunnen gebruiken.

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

Beperkingen voor Enterprise-beleid

Op zakelijke apparaten kunnen sommige beleidsregels voorkomen dat extensies de foutopsporingsfunctie koppelen met een alles-of-nietsmodel 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 voor alle doelen met de fout "Host access is restricted by policy." (zelfs als afzonderlijke oorsprongen in runtime_allowed_hosts staan).
  • Screenshot- en DLP-beleid: Als het bedrijfsbeleid DisableScreenshots screenshots maken uitzet of als er regels voor gegevensverlies voorkomen (Data Loss Prevention, DLP) van toepassing zijn op het doel, mislukt browser.debugger.attach() met de fout "Screenshot capture is restricted by policy.".

Concepten en gebruik

Nadat je de API hebt gekoppeld, kun je met de browser.debugger API opdrachten van het Chrome DevTools-protocol (CDP) naar een bepaald target sturen. Een uitgebreide uitleg van de CDP valt buiten het bereik van deze documentatie. Ga naar de officiële CDP-documentatie voor meer informatie over de 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 en shared_worker).

Binnen een doel kunnen meerdere uitvoeringscontexten zijn. Iframes in hetzelfde proces krijgen bijvoorbeeld geen uniek doel, maar worden in plaats daarvan aangeduid als verschillende contexten die toegankelijk zijn vanuit één doel.

Beperkte domeinen

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

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

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 aan dezelfde procesframes zijn gekoppeld.

  • Volg de stappen om aan gerelateerde doelen te koppelen 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 gekoppelde werknemers.

Vanaf Chrome 125 ondersteunt de browser.debugger API platte sessies. Hiermee kun je extra doelen als kinderen toevoegen aan je hoofddebuggersessie en ze berichten sturen zonder dat je een ander gesprek naar browser.debugger.attach hoeft te starten. 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 bijvoegen 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 wordt alleen bijgevoegd aan frames waarvan het doel op de hoogte is. Dit is beperkt tot frames die directe onderliggende items zijn van een frame dat eraan is gekoppeld. Bijvoorbeeld: als je de framehiërarchie A -> B -> C hebt (waarbij ze allemaal cross-origin zijn) en je Target.setAutoAttach aanroept voor het doel dat aan A is gekoppeld, wordt de sessie ook aan B gekoppeld. Dit is niet recursief, dus Target.setAutoAttach moet ook voor B worden aangeroepen om de sessie aan C te koppelen.

Voorbeelden

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

Typen

Debuggee

ID van het foutopsporingsproces. 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

    nummer optioneel

    De ID van het tabblad dat je wilt debuggen.

  • targetId

    tekenreeks optioneel

    De ondoorzichtige ID van het foutopsporingsdoel.

DebuggerSession

Chrome 125+

ID van de foutopsporingssessie. Er moet een tabId, extensionId of targetId worden ingevoerd. Je kunt ook een optionele sessie-ID invoeren. Als sessionId is ingevoerd voor argumenten die vanuit onEvent worden gestuurd, betekent dit dat de gebeurtenis afkomstig is van een onderliggende protocol-sessie binnen de sessie van de root-foutopsporing. Als sessionId wordt gespecificeerd wanneer deze wordt doorgegeven aan sendCommand, wordt een onderliggende protocolsessie binnen de root-foutopsporingssessie getarget.

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 niet-zichtbare ID van de Chrome DevTools Protocol-sessie. Identificeert een kindersessie binnen de rootsessie die wordt geïdentificeerd door tabId, extensionId of targetId.

  • tabId

    nummer optioneel

    De ID van het tabblad dat je wilt debuggen.

  • targetId

    tekenreeks optioneel

    De ondoorzichtige ID van het foutopsporingsdoel.

DetachReason

Chrome 44 en hoger

Reden voor beëindiging van verbinding.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informatie over foutopsporingstargets

Eigenschappen

  • gekoppeld

    booleaans

    Waar als de foutopsporing al is bijgevoegd.

  • extensionId

    tekenreeks optioneel

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

  • faviconUrl

    tekenreeks optioneel

    URL van het doel-favicon.

  • id

    tekenreeks

    Doel-ID.

  • tabId

    nummer optioneel

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

  • titel

    tekenreeks

    Titel van de doelpagina.

  • Doeltype.

  • url

    tekenreeks

    Doel-URL.

TargetInfoType

Chrome 44 en hoger

Doeltype.

Enum

"page"

"background_page"

"worker"

"other"

Methoden

attach()

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

Hiermee wordt de debugger aan het aangegeven doel gekoppeld.

Parameters

  • target

    Debuggee

    Foutopsporingsdoel waaraan je wilt koppelen.

  • requiredVersion

    tekenreeks

    Vereiste versie van het foutopsporingsprotocol (0.1). Je kunt alleen koppelen aan de foutopsporingsdoel met een overeenkomende hoofdversie en een onderversie die gelijk is aan of hoger is dan de onderversie van de foutopsporingsdoel. Hier vind je een lijst met de protocolversies.

Retourzendingen

  • Promise<void>

    Chrome 96+

    Wordt opgelost als de bijvoegbewerking is geslaagd of mislukt. De belofte wordt omgezet zonder waarde. Als het bijvoegen mislukt, wordt de belofte geweigerd.

detach()

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

Ontkoppelt de foutopsporing van het gegeven doel.

Parameters

  • target

    Debuggee

    Foutopsporingsdoel waarvan je wilt loskoppelen.

Retourzendingen

  • Promise<void>

    Chrome 96+

    Wordt opgelost als de loskoppelingsbewerking is gelukt of mislukt. De belofte wordt omgezet zonder waarde. Als het loskoppelen mislukt, wordt de belofte geweigerd.

getTargets()

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

Geeft de lijst met beschikbare foutopsporingsdoelen terug.

Retourzendingen

sendCommand()

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

Stuurt de gegeven opdracht naar het foutopsporingsdoel.

Parameters

  • 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 aangegeven methode.

Retourzendingen

  • Promise<object | undefined>

    Chrome 96+

    Tekstgedeelte van reactie Als er een fout optreedt tijdens het posten van het bericht, wordt de belofte geweigerd.

Evenementen

onDetach

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

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

Wordt geactiveerd wanneer het instrumentatiegebeurtenis voor foutopsporing van het doel wordt geactiveerd.

Parameters

  • callback

    functie

    De parameter callback ziet er zo uit: 

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