Manifest V3 modifie la façon dont les extensions gèrent la modification des requêtes réseau. Au lieu d'intercepter les requêtes réseau et de les modifier au moment de l'exécution avec chrome.webRequest, votre extension spécifie des règles qui décrivent les actions à effectuer lorsqu'un ensemble de conditions donné est rempli. Pour ce faire, utilisez l'API Declarative Net Request.
L'API Web Request et l'API Declarative Net Request sont très différentes. Au lieu de remplacer un appel de fonction par un autre, vous devez réécrire votre code en termes de cas d'utilisation. Cette section vous guide tout au long de ce processus.
Vous n'avez pas besoin d'effectuer ces modifications si votre extension est installée par une règle. Pour les extensions installées par une règle, l'autorisation webRequestBlocking est toujours disponible dans Manifest V3.
Il s'agit de la deuxième des trois sections décrivant les modifications nécessaires pour le code qui ne fait pas partie du service worker de l'extension. Il décrit la conversion des requêtes Web bloquantes, utilisées par Manifest V2, en requêtes réseau déclaratives, utilisées par Manifest V3. Les deux autres sections couvrent la mise à jour de votre code nécessaire pour migrer vers Manifest V3 et l'amélioration de la sécurité.
Introduction
Dans le fichier manifeste V2, le blocage des requêtes Web pouvait dégrader considérablement les performances des extensions et des pages avec lesquelles elles fonctionnent. L'espace de noms webRequest accepte neuf événements potentiellement bloquants, chacun pouvant prendre en charge un nombre illimité de gestionnaires d'événements. Pire encore, chaque page Web peut être bloquée par plusieurs extensions, et les autorisations requises pour cela sont intrusives. Manifest V3 permet d'éviter ce problème en remplaçant les rappels par des règles déclaratives.
Modifier les autorisations
Apportez les modifications suivantes au champ "permissions" dans votre manifest.json.
- Supprimez l'autorisation
"webRequest"si vous n'avez plus besoin d'observer les requêtes réseau. - Déplacez les modèles de correspondance de
"permissions"vers"host_permissions".
Vous devrez ajouter d'autres autorisations en fonction de votre cas d'utilisation. Ces autorisations sont décrites avec le cas d'utilisation qu'elles prennent en charge.
Créer des règles de requête réseau déclarative
Pour créer des règles de requête réseau déclaratives, vous devez ajouter un objet "declarative_net_request" à votre manifest.json. Le bloc "declarative_net_request" contient un tableau d'objets "rule_resource" qui pointent vers un fichier de règles. Le fichier de règles contient un tableau d'objets spécifiant une action et les conditions dans lesquelles ces actions sont appelées.
Cas d'utilisation courants
Les sections suivantes décrivent les cas d'utilisation courants des requêtes réseau déclaratives. Les instructions ci-dessous ne fournissent qu'un bref aperçu. Pour en savoir plus sur toutes les informations présentées ici, consultez la documentation de référence de l'API sous chrome.declarativeNetRequest.
Bloquer une seule URL
Dans le fichier manifeste V2, un cas d'utilisation courant consistait à bloquer les requêtes Web à l'aide de l'événement onBeforeRequest dans le script d'arrière-plan.
chrome.webRequest.onBeforeRequest.addListener((e) => { return { cancel: true }; }, { urls: ["https://www.example.com/*"] }, ["blocking"]);
Pour Manifest V3, créez une règle declarativeNetRequest à l'aide du type d'action "block". Examinons l'objet "condition" dans l'exemple de règle. Son "urlFilter" remplace l'option urls transmise à l'écouteur webRequest. Un tableau "resourceTypes" spécifie la catégorie de ressources à bloquer. Cet exemple ne bloque que la page HTML principale, mais vous pouvez, par exemple, ne bloquer que les polices.
[ { "id" : 1, "priority": 1, "action" : { "type" : "block" }, "condition" : { "urlFilter" : "||example.com", "resourceTypes" : ["main_frame"] } } ]
Pour que cela fonctionne, vous devez mettre à jour les autorisations de l'extension. Dans manifest.json, remplacez l'autorisation "webRequestBlocking" par l'autorisation "declarativeNetRequest". Notez que l'URL est supprimée du champ "permissions", car le blocage de contenu ne nécessite pas d'autorisations d'hôte. Comme indiqué ci-dessus, le fichier de règles spécifie le ou les hôtes auxquels une requête réseau déclarative s'applique.
Si vous souhaitez essayer, le code ci-dessous est disponible dans notre dépôt d'exemples.
"permissions": [ "webRequestBlocking", "https://*.example.com/*" ]
"permissions": [ "declarativeNetRequest", ]
Rediriger plusieurs URL
Dans Manifest V2, un autre cas d'utilisation courant consistait à utiliser l'événement BeforeRequest pour rediriger les requêtes Web.
chrome.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"] );
Pour Manifest V3, utilisez le type d'action "redirect". Comme auparavant, "urlFilter" remplace l'option url transmise au listener webRequest. Notez que, dans cet exemple, l'objet "action" du fichier de règles contient un champ "redirect" contenant l'URL à renvoyer au lieu de l'URL filtrée.
[ { "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"] } } ]
Ce scénario nécessite également des modifications des autorisations de l'extension. Comme précédemment, remplacez l'autorisation "webRequestBlocking" par l'autorisation "declarativeNetRequest". Les URL sont à nouveau déplacées de manifest.json vers un fichier de règles. Notez que la redirection nécessite également l'autorisation "declarativeNetRequestWithHostAccess" en plus de l'autorisation d'hôte.
Si vous souhaitez essayer, le code ci-dessous est disponible dans notre dépôt d'exemples.
"permissions": [ "webRequestBlocking", "https://developer.chrome.com/docs/extensions/*", "https://developer.chrome.com/docs/extensions/reference" ]
"permissions": [ "declarativeNetRequestWithHostAccess" ], "host_permissions": [ "https://developer.chrome.com/*" ]
Bloquer les cookies
Dans le fichier manifeste V2, le blocage des cookies nécessite l'interception des en-têtes de requêtes Web avant leur envoi et la suppression d'un en-tête spécifique.
chrome.webRequest.onBeforeSendHeaders.addListener( function(details) { removeHeader(details.requestHeaders, 'cookie'); return {requestHeaders: details.requestHeaders}; }, // filters {urls: ['https://*/*', 'http://*/*']}, // extraInfoSpec ['blocking', 'requestHeaders', 'extraHeaders']);
Manifest V3 le fait également avec une règle dans un fichier de règles. Cette fois, le type d'action est "modifyHeaders". Le fichier accepte un tableau d'objets "requestHeaders" spécifiant les en-têtes à modifier et la manière de les modifier. Notez que l'objet "condition" ne contient qu'un tableau "resourceTypes". Il accepte les mêmes valeurs que les exemples précédents.
Si vous souhaitez essayer, le code ci-dessous est disponible dans notre dépôt d'exemples.
[ { "id": 1, "priority": 1, "action": { "type": "modifyHeaders", "requestHeaders": [ { "header": "cookie", "operation": "remove" } ] }, "condition": { "urlFilter": "|*?no-cookies=1", "resourceTypes": ["main_frame"] } } ]
Ce scénario nécessite également des modifications des autorisations de l'extension. Comme précédemment, remplacez l'autorisation "webRequestBlocking" par l'autorisation "declarativeNetRequest".
"permissions": [ "webRequest", "webRequestBlocking", "https://*/*", "http://*/*" ],
"permissions": [ "declarativeNetRequest", ], "host_permissions": [ "" ]