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 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 cette procédure.
Dans le fichier manifeste V2, le blocage des requêtes Web peut considérablement dégrader les performances des extensions et des pages avec lesquelles elles fonctionnent. L'espace de noms webRequest prend en charge neuf événements potentiellement bloquants, chacun acceptant un nombre illimité de gestionnaires d'événements. Pour aggraver la situation, chaque page Web est potentiellement bloquée par plusieurs extensions, et les autorisations requises à cet effet sont intrusives. Le fichier manifeste V3 évite ce problème en remplaçant les rappels par des règles déclaratives.
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 traitent de la mise à jour de votre code nécessaire pour migrer vers Manifest V3 et de l'amélioration de la sécurité.
Modifier les autorisations
Apportez les modifications suivantes au champ "permissions" de 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é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" 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, il était courant de bloquer les 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 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 ce faire, 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 l'hôte 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
Un autre cas d'utilisation courant dans le fichier manifeste 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 à 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 de modifier les 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 Manifest V2, le blocage des cookies nécessite d'intercepter les en-têtes de requête Web avant leur envoi et de supprimer 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 utilise 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 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": [
""
]