Manifest V3 modifica il modo in cui le estensioni gestiscono la modifica delle richieste di rete. Anziché intercettare le richieste di rete e modificarle in fase di runtime con browser.webRequest, l'estensione specifica regole che descrivono le azioni da eseguire quando viene soddisfatto un determinato insieme di condizioni. Esegui questa operazione utilizzando l'API Declarative Net Request.
L'API Web Request e le API Declarative Net Request sono molto diverse. Anziché sostituire una chiamata di funzione con un'altra, devi riscrivere il codice in termini di casi d'uso. Questa sezione descrive la procedura.
Non è necessario apportare queste modifiche se l'estensione viene installata tramite policy. Per le estensioni installate tramite criteri, l'autorizzazione webRequestBlocking è ancora disponibile in Manifest V3.
Questa è la seconda di tre sezioni che descrivono le modifiche necessarie per il codice che non fa parte del service worker del servizio di estensione. Descrive la conversione delle richieste web di blocco, utilizzate da Manifest V2, in richieste di rete dichiarative, utilizzate da Manifest V3. Le altre due sezioni riguardano l'aggiornamento del codice necessario per la migrazione a Manifest V3 e il miglioramento della sicurezza.
Introduzione
In Manifest V2, il blocco delle richieste web potrebbe ridurre notevolmente sia le prestazioni delle estensioni sia quelle delle pagine con cui funzionano. Lo spazio dei nomi webRequest supporta nove eventi potenzialmente bloccanti, ognuno dei quali accetta un numero illimitato di gestori di eventi. A peggiorare le cose, ogni pagina web è potenzialmente bloccata da più estensioni e le autorizzazioni richieste per questo sono invasive. Manifest V3 protegge da questo problema sostituendo i callback con regole dichiarative.
Aggiorna autorizzazioni
Apporta le seguenti modifiche al campo "permissions" nel tuo manifest.json.
- Rimuovi l'autorizzazione
"webRequest"se non devi più osservare le richieste di rete. - Sposta i pattern di corrispondenza da
"permissions"a"host_permissions".
A seconda del tuo caso d'uso, dovrai aggiungere altre autorizzazioni. Queste autorizzazioni sono descritte con il caso d'uso che supportano.
Crea regole di richiesta di rete dichiarativa
La creazione di regole di richiesta di rete dichiarative richiede l'aggiunta di un oggetto "declarative_net_request" al file manifest.json. Il blocco "declarative_net_request" contiene un array di oggetti "rule_resource" che puntano a un file di regole. Il file delle regole contiene un array di oggetti che specificano un'azione e le condizioni in cui vengono richiamate queste azioni.
Casi d'uso comuni
Le sezioni seguenti descrivono i casi d'uso comuni per le richieste di rete dichiarative. Le istruzioni riportate di seguito forniscono solo una breve panoramica. Per ulteriori informazioni su tutte le informazioni riportate qui, consulta il riferimento API nella sezione browser.declarativeNetRequest.
Bloccare un singolo URL
Un caso d'uso comune in Manifest V2 era il blocco delle richieste web utilizzando l'evento onBeforeRequest nello script di sfondo.
browser.webRequest.onBeforeRequest.addListener((e) => { return { cancel: true }; }, { urls: ["https://www.example.com/*"] }, ["blocking"]);
Per Manifest V3, crea una nuova regola declarativeNetRequest utilizzando il tipo di azione "block". Nota l'oggetto "condition" nella regola di esempio. Il relativo "urlFilter" sostituisce l'opzione urls passata al listener webRequest. Un array "resourceTypes" specifica la categoria di risorse da bloccare. Questo esempio blocca solo la pagina HTML principale, ma potresti, ad esempio, bloccare solo i caratteri.
[ { "id" : 1, "priority": 1, "action" : { "type" : "block" }, "condition" : { "urlFilter" : "||example.com", "resourceTypes" : ["main_frame"] } } ]
Per far funzionare questa funzionalità, devi aggiornare le autorizzazioni dell'estensione. In manifest.json, sostituisci l'autorizzazione "webRequestBlocking" con l'autorizzazione "declarativeNetRequest". Tieni presente che l'URL viene rimosso dal campo "permissions" perché il blocco dei contenuti non richiede autorizzazioni host. Come mostrato sopra, il file di regole specifica l'host o gli host a cui si applica una richiesta di rete dichiarativa.
Se vuoi provare, il codice riportato di seguito è disponibile nel nostro repository di esempi.
"permissions": [ "webRequestBlocking", "https://*.example.com/*" ]
"permissions": [ "declarativeNetRequest", ]
Reindirizzare più URL
Un altro caso d'uso comune in Manifest V2 era l'utilizzo dell'evento BeforeRequest per reindirizzare le richieste web.
browser.webRequest.onBeforeRequest.addListener((e) => { console.log(e); return { redirectUrl: "https://developer.chrome.com/docs/extensions/mv3/intro/" }; }, { urls: [ "https://developer.chrome.com/docs/extensions/mv2/" ] }, ["blocking"] );
Per Manifest V3, utilizza il tipo di azione "redirect". Come in precedenza, "urlFilter" sostituisce l'opzione url passata al listener webRequest. Tieni presente che, per questo esempio, l'oggetto "action" del file di regole contiene un campo "redirect" contenente l'URL da restituire anziché l'URL filtrato.
[ { "id" : 1, "priority": 1, "action": { "type": "redirect", "redirect": { "url": "https://developer.chrome.com/docs/extensions/mv3/intro/" } }, "condition": { "urlFilter": "https://developer.chrome.com/docs/extensions/mv2/", "resourceTypes": ["main_frame"] } } ]
Questo scenario richiede anche modifiche alle autorizzazioni dell'estensione. Come prima, sostituisci l'autorizzazione "webRequestBlocking" con l'autorizzazione "declarativeNetRequest". Gli URL vengono nuovamente spostati da manifest.json a un file di regole. Tieni presente che il reindirizzamento richiede anche l'autorizzazione "declarativeNetRequestWithHostAccess" oltre all'autorizzazione host.
Se vuoi provare, il codice riportato di seguito è disponibile nel nostro repository di esempi.
"permissions": [ "webRequestBlocking", "https://developer.chrome.com/docs/extensions/*", "https://developer.chrome.com/docs/extensions/reference" ]
"permissions": [ "declarativeNetRequestWithHostAccess" ], "host_permissions": [ "https://developer.chrome.com/*" ]
Bloccare i cookie
In Manifest V2, il blocco dei cookie richiede l'intercettazione delle intestazioni delle richieste web prima che vengano inviate e la rimozione di una specifica.
browser.webRequest.onBeforeSendHeaders.addListener( function(details) { removeHeader(details.requestHeaders, 'cookie'); return {requestHeaders: details.requestHeaders}; }, // filters {urls: ['https://*/*', 'http://*/*']}, // extraInfoSpec ['blocking', 'requestHeaders', 'extraHeaders']);
Manifest V3 esegue questa operazione anche con una regola in un file di regole. Questa volta il tipo di azione è "modifyHeaders". Il file accetta un array di oggetti "requestHeaders" che specificano le intestazioni da modificare e come modificarle. Tieni presente che l'oggetto "condition" contiene solo un array "resourceTypes". Supporta gli stessi valori degli esempi precedenti.
Se vuoi provare, il codice riportato di seguito è disponibile nel nostro repository di esempi.
[ { "id": 1, "priority": 1, "action": { "type": "modifyHeaders", "requestHeaders": [ { "header": "cookie", "operation": "remove" } ] }, "condition": { "urlFilter": "|*?no-cookies=1", "resourceTypes": ["main_frame"] } } ]
Questo scenario richiede anche modifiche alle autorizzazioni dell'estensione. Come prima, sostituisci l'autorizzazione "webRequestBlocking" con l'autorizzazione "declarativeNetRequest".
"permissions": [ "webRequest", "webRequestBlocking", "https://*/*", "http://*/*" ],
"permissions": [ "declarativeNetRequest", ], "host_permissions": [ "" ]