Modifier les requêtes réseau dans Manifest V3
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 donné de conditions est rempli. Pour ce faire, utilisez l'API Declarative Net Request.
L'API Web Request et les API déclarative 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 fonction des cas d'utilisation. Cette section vous guide tout au long de ce processus.
Dans Manifest V2, le blocage des requêtes Web peut nuire considérablement aux performances des extensions et des pages sur lesquelles elles travaillent. L'espace de noms webRequest accepte neuf événements potentiellement bloquants, chacun acceptant 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 invasives. Manifest V3 vous protège contre ce problème en remplaçant les rappels par des règles déclaratives.
Cette section est la deuxième des trois sections qui décrivent les modifications nécessaires pour du 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 NET déclaratives, utilisées par Manifest V3. Les deux autres sections expliquent comment mettre à jour le code nécessaire à la migration vers Manifest V3 et améliorer la sécurité.
Modifier les autorisations
Apportez les modifications suivantes au champ "permissions" de votre fichier manifest.json.
- Supprimez l'autorisation
"webRequest"si vous n'avez plus besoin d'observer les requêtes réseau. - Déplacez les formats de correspondance de
"permissions"vers"host_permissions".
Selon votre cas d'utilisation, vous devrez ajouter d'autres autorisations. Ces autorisations sont décrites en fonction du cas d'utilisation concerné.
Créer des règles de requête nette déclaratives
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" pointant 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 des cas d'utilisation courants des requêtes net déclaratives. Les instructions ci-dessous n'en fournissent qu'une brève description. Pour en savoir plus sur toutes les informations de cette page, consultez la documentation de référence de l'API dans chrome.declarativeNetRequest.
Bloquer une URL spécifique
Dans Manifest V2, l'un des cas d'utilisation courants consistait à bloquer des requêtes Web à l'aide de l'événement onBeforeRequest dans le script en 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". Notez 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 des ressources à bloquer. Cet exemple bloque uniquement 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 a été supprimée du champ "permissions", car le blocage du 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 voulez essayer, le code ci-dessous est disponible dans notre dépôt d'exemples.
"permissions": [
"webRequestBlocking",
"https://*.example.com/*"
]
"permissions": [
"declarativeNetRequest",
]
Rediriger plusieurs URL
Un autre cas d'utilisation courant dans Manifest V2 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 précédemment, "urlFilter" remplace l'option url transmise à l'écouteur webRequest. Notez que, dans cet exemple, l'objet "action" du fichier de règles contient un champ "redirect" contenant l'URL à afficher 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 de modifier les autorisations de l'extension. Comme précédemment, remplacez l'autorisation "webRequestBlocking" par l'autorisation "declarativeNetRequest". Les URL sont de nouveau déplacées du fichier 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 voulez 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 Manifest V2, le blocage des cookies nécessite d'intercepter les en-têtes de requête Web avant leur envoi et d'en supprimer un 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 effectue également cette opération avec une règle dans un fichier de règles. Cette fois, le type d'action est "modifyHeaders". Le fichier utilise un tableau d'objets "requestHeaders" spécifiant les en-têtes à modifier et la façon de les modifier. Notez que l'objet "condition" ne contient qu'un tableau "resourceTypes". Elle accepte les mêmes valeurs que les exemples précédents.
Si vous voulez 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 de modifier les 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": [
""
]