Vervang blokkerende luisteraars voor webverzoeken

Netwerkverzoeken wijzigen in Manifest V3

Opmerking: Manifest V3 wordt algemeen ondersteund in Chrome 88 of hoger. Voor extensiefuncties die in latere Chrome-versies zijn toegevoegd, raadpleegt u de API-referentiedocumentatie voor ondersteuningsinformatie. Als uw extensie een specifieke API vereist, kunt u een minimale Chrome-versie opgeven in het manifestbestand.

Manifest V3 verandert de manier waarop extensies omgaan met wijziging van netwerkverzoeken. In plaats van netwerkverzoeken te onderscheppen en deze tijdens runtime te wijzigen met chrome.webRequest , specificeert uw extensie regels die acties beschrijven die moeten worden uitgevoerd wanneer aan een bepaalde reeks voorwaarden wordt voldaan. Doe dit met behulp van de Declarative Net Request API .

De Web Request API en de Declarative Net Request API's zijn aanzienlijk verschillend. In plaats van de ene functieaanroep door een andere te vervangen, moet u uw code herschrijven in termen van gebruiksscenario's. In dit gedeelte wordt u door dat proces geleid.

In Manifest V2 kan het blokkeren van webverzoeken zowel de prestaties van extensies als de prestaties van pagina's waarmee ze werken aanzienlijk verslechteren. De webRequest naamruimte ondersteunt negen potentieel blokkerende gebeurtenissen, die elk een onbeperkt aantal gebeurtenishandlers vereisen. Tot overmaat van ramp wordt elke webpagina mogelijk geblokkeerd door meerdere extensies, en de daarvoor vereiste machtigingen zijn invasief. Manifest V3 beschermt tegen dit probleem door callbacks te vervangen door declaratieve regels.

Dit is de tweede van drie secties waarin de wijzigingen worden beschreven die nodig zijn voor code die geen deel uitmaakt van de uitbreidingsservicemedewerker. Het beschrijft het converteren van blokkerende webverzoeken, gebruikt door Manifest V2, naar declaratieve netverzoeken, gebruikt door Manifest V3. De andere twee secties behandelen het bijwerken van de code die nodig is voor de migratie naar Manifest V3 en het verbeteren van de beveiliging .

Machtigingen bijwerken

Breng de volgende wijzigingen aan in het veld "permissions" in uw manifest.json .

• Verwijder de machtiging "webRequest" als u netwerkverzoeken niet langer hoeft te observeren.
• Verplaats overeenkomstpatronen van "permissions" naar "host_permissions" .

Afhankelijk van uw gebruiksscenario moet u andere machtigingen toevoegen. Deze machtigingen worden beschreven met de use case die ze ondersteunen.

Maak declaratieve nettoverzoekregels

Voor het maken van declaratieve netverzoekregels is het toevoegen van een object "declarative_net_request" aan uw manifest.json vereist. Het blok "declarative_net_request" bevat een array van "rule_resource" -objecten die naar een regelbestand verwijzen. Het regelbestand bevat een array van objecten die een actie specificeren en de voorwaarden waaronder die acties worden aangeroepen.

Opmerking: een volledige uitleg van de declarativeNetRequest API is langer dan we hier kunnen geven. Hieronder worden enkele gebruiksscenario's weergegeven, maar deze zijn kortheidshalve ingekort. Bezoek de referentiepagina voor een beschrijving van het gebruik van de declarativeNetRequest API.

Veelvoorkomende gebruiksscenario's

In de volgende secties worden algemene gebruiksscenario's voor declaratieve netaanvragen beschreven. De onderstaande instructies geven slechts een korte schets. Meer informatie over alle informatie hier wordt beschreven in de API-referentie onder chrome.declarativeNetRequest

Blokkeer een enkele URL

Een veelvoorkomend gebruiksvoorbeeld in Manifest V2 was het blokkeren van webverzoeken met behulp van de onBeforeRequest gebeurtenis in het achtergrondscript.

Manifest V2-achtergrondscript

chrome.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

Maak voor Manifest V3 een nieuwe declarativeNetRequest -regel met behulp van het actietype "block" . Let op het object "condition" in de voorbeeldregel. Het "urlFilter" vervangt de urls optie die wordt doorgegeven aan de webRequest listener. Een array "resourceTypes" specificeert de categorie van bronnen die moeten worden geblokkeerd. Dit voorbeeld blokkeert alleen de HTML-hoofdpagina, maar u kunt bijvoorbeeld alleen lettertypen blokkeren.

Manifest V3-regelbestand

[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

Om dit te laten werken, moet u de machtigingen van de extensie bijwerken. Vervang in manifest.json de machtiging "webRequestBlocking" door de machtiging "declarativeNetRequest" . Merk op dat de URL is verwijderd uit het veld "permissions" omdat voor het blokkeren van inhoud geen hostmachtigingen vereist zijn. Zoals hierboven weergegeven, specificeert het regelbestand de host of hosts waarop een declaratief netverzoek van toepassing is.

Als je dit wilt proberen, is de onderstaande code beschikbaar in onze voorbeeldrepository .

Manifest V2

  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]

Manifest V3

  "permissions": [
    "declarativeNetRequest",
  ]

Meerdere URL's omleiden

Een ander veelvoorkomend gebruiksscenario in Manifest V2 was het gebruik van de BeforeRequest -gebeurtenis om webverzoeken om te leiden.

Manifest V2-achtergrondscript

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"]
);

Gebruik voor Manifest V3 het actietype "redirect" . Net als voorheen vervangt "urlFilter" de url optie die is doorgegeven aan de webRequest listener. Merk op dat voor dit voorbeeld het "action" -object van het regelbestand een "redirect" -veld bevat met de URL die moet worden geretourneerd in plaats van de URL die wordt gefilterd.

Manifest V3-regelbestand

[
  {
    "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"]
    }
  }

Dit scenario vereist ook wijzigingen in de machtigingen van de extensie. Vervang net als voorheen de machtiging "webRequestBlocking" door de machtiging "declarativeNetRequest" . De URL's worden opnieuw verplaatst van manifest.json naar een regelbestand. Merk op dat voor omleiden naast de hostmachtiging ook de machtiging "declarativeNetRequestWithHostAccess" vereist is.

Als je dit wilt proberen, is de onderstaande code beschikbaar in onze voorbeeldrepository .

Manifest V2

  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]

Manifest V3

  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

Cookies blokkeren

In Manifest V2 vereist het blokkeren van cookies het onderscheppen van de webverzoekheaders voordat ze worden verzonden en het verwijderen van een specifieke header.

Manifest V2-achtergrondscript

chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    removeHeader(details.requestHeaders, 'cookie');
    return {requestHeaders: details.requestHeaders};
  },
  // filters
  {urls: ['https://*/*', 'http://*/*']},
  // extraInfoSpec
  ['blocking', 'requestHeaders', 'extraHeaders']);

Manifest V3 doet dit ook met een regel in een regelbestand. Deze keer is het actietype "modifyHeaders" . Het bestand bevat een array van "requestHeaders" -objecten waarin wordt aangegeven welke headers moeten worden gewijzigd en hoe deze moeten worden gewijzigd. Merk op dat het object "condition" alleen een array "resourceTypes" bevat. Het ondersteunt dezelfde waarden als de vorige voorbeelden.

Als je dit wilt proberen, is de onderstaande code beschikbaar in onze voorbeeldrepository .

Manifest V3 manifest.json

[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "cookie", "operation": "remove" }
      ]
    },
    "condition": {
      "urlFilter": "|*?no-cookies=1",
      "resourceTypes": ["main_frame"]
    }
  }
]

Dit scenario vereist ook wijzigingen in de machtigingen van de extensie. Vervang net als voorheen de machtiging "webRequestBlocking" door de machtiging "declarativeNetRequest" .

Manifest V2

  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "https://*/*",
    "http://*/*"
  ],

Manifest V3

  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]