Descrizione
L'API chrome.debugger funge da trasporto alternativo per il protocollo di debug remoto di Chrome. Utilizza chrome.debugger per collegarti a una o più schede per instrumentare l'interazione di rete, eseguire il debug di JavaScript, modificare il DOM e il CSS e altro ancora. Utilizza la proprietà Debuggee tabId per scegliere come target le schede con sendCommand e indirizzare gli eventi per tabId dai callback onEvent.
Autorizzazioni
debuggerPer utilizzare questa API, devi dichiarare l'autorizzazione "debugger" nel manifest dell'estensione.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
Limitazioni delle policy aziendali
Sui dispositivi aziendali, alcune policy possono impedire alle estensioni di collegare il debugger utilizzando un modello tutto o niente al momento del collegamento
(browser.debugger.attach()):
- Limitazioni degli host: se la policy aziendale
ExtensionSettingsconfigura gli host bloccati (runtime_blocked_hosts) per un'estensione,browser.debugger.attach()viene bloccato su tutte le destinazioni con l'errore"Host access is restricted by policy."(anche se le singole origini sono inruntime_allowed_hosts). - Criteri relativi agli screenshot e alla DLP: se il criterio aziendale
DisableScreenshotsdisattiva l'acquisizione di screenshot o se le regole di Prevenzione della perdita di dati (DLP) si applicano alla destinazione,browser.debugger.attach()non va a buon fine e viene visualizzato l'errore"Screenshot capture is restricted by policy.".
Concetti e utilizzo
Una volta collegata, l'API browser.debugger ti consente di inviare comandi Chrome DevTools Protocol (CDP) a un determinato target. La spiegazione approfondita del CDP non rientra nell'ambito di questa documentazione. Per saperne di più sul CDP, consulta la documentazione ufficiale del CDP.
Destinazioni
I target rappresentano un elemento di cui viene eseguito il debug, ad esempio una scheda, un iframe o un worker. Ogni target è identificato da un UUID e ha un tipo associato (ad esempio iframe, shared_worker e altri).
All'interno di un target, possono essere presenti più contesti di esecuzione. Ad esempio, gli iframe dello stesso processo non ricevono un target univoco, ma vengono rappresentati come contesti diversi a cui è possibile accedere da un singolo target.
Domini con restrizioni
Per motivi di sicurezza, l'API browser.debugger non fornisce l'accesso a tutti i domini del protocollo Chrome DevTools. I domini disponibili sono: 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 e WebAuthn.
Utilizza i frame
Non esiste una mappatura uno a uno dei frame ai target. All'interno di una singola scheda, più frame dello stesso processo possono condividere la stessa destinazione, ma utilizzare un execution context diverso. D'altra parte, è possibile creare un nuovo target per un iframe out-of-process.
Per collegarti a tutti i frame, devi gestire ogni tipo di frame separatamente:
Ascolta l'evento
Runtime.executionContextCreatedper identificare i nuovi contesti di esecuzione associati ai frame dello stesso processo.Segui i passaggi per collegarti ai target correlati per identificare i frame out-of-process.
Collega ai target correlati
Dopo aver eseguito la connessione a un target, potresti voler connetterti ad altri target correlati, inclusi frame secondari out-of-process o worker associati.
A partire da Chrome 125, l'API browser.debugger supporta le sessioni piatte. In questo modo puoi aggiungere altri target come elementi secondari alla sessione principale del debugger e inviare loro messaggi senza dover effettuare un'altra chiamata a browser.debugger.attach. Puoi invece aggiungere una proprietà sessionId quando chiami browser.debugger.sendCommand per identificare il target secondario a cui vuoi inviare un comando.
Per collegarti automaticamente ai frame secondari out-of-process, aggiungi prima un listener per l'evento 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");
}
});
Quindi, attiva il collegamento automatico inviando il comando Target.setAutoAttach con
l'opzione flatten impostata su true:
await browser.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
Il collegamento automatico si collega solo ai frame di cui il target è a conoscenza, ovvero solo ai frame secondari immediati di un frame associato. Ad esempio, con la gerarchia di frame A -> B -> C (dove tutti sono multiorigine), la chiamata di Target.setAutoAttach per la destinazione associata ad A comporterebbe l'associazione della sessione anche a B. Tuttavia, questa operazione non è ricorsiva, quindi è necessario chiamare Target.setAutoAttach anche per B per collegare la sessione a C.
Esempi
Per provare questa API, installa l'esempio di API debugger dal repository chrome-extension-samples.
Tipi
Debuggee
Identificatore del debuggee. È necessario specificare tabId, extensionId o targetId
Proprietà
-
extensionId
stringa facoltativa
L'ID dell'estensione di cui vuoi eseguire il debug. Il collegamento a una pagina di sfondo dell'estensione è possibile solo quando viene utilizzato l'opzione della riga di comando
--silent-debugger-extension-api. -
tabId
number optional
L'ID della scheda di cui vuoi eseguire il debug.
-
targetId
stringa facoltativa
L'ID opaco della destinazione di debug.
DebuggerSession
Identificatore della sessione del debugger. È necessario specificare uno tra tabId, extensionId o targetId. Inoltre, è possibile fornire un sessionId facoltativo. Se sessionId è specificato per gli argomenti inviati da onEvent, significa che l'evento proviene da una sessione del protocollo secondario all'interno della sessione del debuggee principale. Se sessionId viene specificato quando viene passato a sendCommand, ha come target una sessione del protocollo secondario all'interno della sessione di debug principale.
Proprietà
-
extensionId
stringa facoltativa
L'ID dell'estensione di cui vuoi eseguire il debug. Il collegamento a una pagina di sfondo dell'estensione è possibile solo quando viene utilizzato l'opzione della riga di comando
--silent-debugger-extension-api. -
sessionId
stringa facoltativa
L'ID opaco della sessione Chrome DevTools Protocol. Identifica una sessione secondaria all'interno della sessione principale identificata da tabId, extensionId o targetId.
-
tabId
number optional
L'ID della scheda di cui vuoi eseguire il debug.
-
targetId
stringa facoltativa
L'ID opaco della destinazione di debug.
DetachReason
Motivo della chiusura della connessione.
Enum
"target_closed"
"canceled_by_user"
TargetInfo
Informazioni sul target di debug
Proprietà
-
collegato
booleano
True se il debugger è già collegato.
-
extensionId
stringa facoltativa
L'ID estensione, definito se type = 'background_page'.
-
faviconUrl
stringa facoltativa
URL della favicon di destinazione.
-
id
stringa
ID target.
-
tabId
number optional
L'ID della scheda, definito se type == 'page'.
-
titolo
stringa
Titolo della pagina di destinazione.
-
tipo
Tipo di target.
-
url
stringa
URL di destinazione.
TargetInfoType
Tipo di target.
Enum
"page"
"background_page"
"worker"
"other"
Metodi
attach()
browser.debugger.attach(
target: Debuggee,
requiredVersion: string,
): Promise<void>
Collega il debugger alla destinazione specificata.
Parametri
-
destinazione
Destinazione di debug a cui vuoi collegarti.
-
requiredVersion
stringa
Versione del protocollo di debug richiesta ("0.1"). È possibile collegarsi al target di debug solo con una versione principale corrispondente e una versione secondaria maggiore o uguale. L'elenco delle versioni del protocollo è disponibile qui.
Resi
-
Promise<void>
Browser Chrome 96+ .* da Chrome 148Viene risolto una volta che l'operazione di collegamento ha esito positivo o negativo. La promessa viene risolta senza alcun valore. Se il collegamento non va a buon fine, la promise verrà rifiutata.
detach()
browser.debugger.detach(
target: Debuggee,
): Promise<void>
Scollega il debugger dalla destinazione specificata.
Parametri
-
destinazione
Destinazione di debug da cui vuoi scollegarti.
Resi
-
Promise<void>
Browser Chrome 96+ .* da Chrome 148Si risolve una volta che l'operazione di scollegamento ha esito positivo o negativo. La promessa viene risolta senza alcun valore. Se lo scollegamento non va a buon fine, la promise verrà rifiutata.
getTargets()
browser.debugger.getTargets(): Promise<TargetInfo[]>
Restituisce l'elenco delle destinazioni di debug disponibili.
Resi
-
Promise<TargetInfo[]>
Browser Chrome 96+ .* da Chrome 148
sendCommand()
browser.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
): Promise<object | undefined>
Invia il comando specificato alla destinazione di debug.
Parametri
-
destinazione
Destinazione di debug a cui vuoi inviare il comando.
-
method
stringa
Nome metodo. Deve essere uno dei metodi definiti dal protocollo di debug remoto.
-
commandParams
object facoltativo
Oggetto JSON con i parametri della richiesta. Questo oggetto deve essere conforme allo schema dei parametri di debug remoto per il metodo specificato.
Resi
-
Promise<object | undefined>
Browser Chrome 96+ .* da Chrome 148Corpo della risposta. Se si verifica un errore durante la pubblicazione del messaggio, la promise verrà rifiutata.
Eventi
onDetach
browser.debugger.onDetach.addListener(
callback: function,
)
Attivato quando il browser termina la sessione di debug per la scheda. Ciò accade quando la scheda viene chiusa o quando viene richiamato Chrome DevTools per la scheda collegata.
Parametri
-
callback
funzione
Il parametro
callbackha il seguente aspetto:(source: Debuggee, reason: DetachReason) => void
-
origine
-
reason
-
onEvent
browser.debugger.onEvent.addListener(
callback: function,
)
Attivato ogni volta che il target di debug genera un evento di strumentazione.
Parametri
-
callback
funzione
Il parametro
callbackha il seguente aspetto:(source: DebuggerSession, method: string, params?: object) => void
-
origine
-
method
stringa
-
params
object facoltativo
-