Vervang blokkerende luisteraars voor webverzoeken

Manifest V3 verandert de manier waarop extensies omgaan met het wijzigen 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 set voorwaarden is voldaan. Doe dit met behulp van de Declarative Net Request API .

De Web Request API en de Declarative Net Request API's verschillen aanzienlijk. In plaats van de ene functieaanroep door een andere te vervangen, moet u uw code herschrijven met het oog op use cases. Deze sectie leidt u door dat proces.

U hoeft deze wijzigingen niet aan te brengen als uw extensie volgens beleid is geïnstalleerd. Voor extensies die volgens beleid zijn geïnstalleerd, is de machtiging webRequestBlocking nog steeds beschikbaar in Manifest V3.

Dit is de tweede van drie secties die wijzigingen beschrijven die nodig zijn voor code die geen deel uitmaakt van de extensieserviceworker. 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 uw code die nodig is voor de migratie naar Manifest V3 en het verbeteren van de beveiliging .

Invoering

In Manifest V2 kan het blokkeren van webaanvragen de prestaties van zowel extensies als de pagina's waarmee ze werken aanzienlijk verslechteren. De webRequest naamruimte ondersteunt negen potentieel blokkerende gebeurtenissen, die elk een onbeperkt aantal event handlers vereisen. Om het nog erger te maken, wordt elke webpagina mogelijk geblokkeerd door meerdere extensies en zijn de hiervoor vereiste machtigingen ingrijpend. Manifest V3 beschermt tegen dit probleem door callbacks te vervangen door declaratieve regels.

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 Match Patterns van "permissions" naar "host_permissions" .

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

Declaratieve netaanvraagregels maken

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

Veelvoorkomende gebruiksgevallen

De volgende secties beschrijven veelvoorkomende use cases voor declaratieve netverzoeken. De onderstaande instructies geven slechts een beknopt overzicht. Meer informatie over alle informatie hier vindt u in de API-referentie onder chrome.declarativeNetRequest

Blokkeer een enkele URL

Een veelvoorkomend gebruiksvoorbeeld in Manifest V2 was het blokkeren van webaanvragen met behulp van de gebeurtenis onBeforeRequest 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 het actietype "block" . Let op het "condition" object in de voorbeeldregel. Het "urlFilter" object vervangt de optie urls die aan de webRequest listener is doorgegeven. Een "resourceTypes" array specificeert de categorie van de te blokkeren bronnen. In dit voorbeeld wordt alleen de HTML-hoofdpagina geblokkeerd, maar u kunt bijvoorbeeld ook 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 uit het veld "permissions" is verwijderd, omdat het blokkeren van content geen hostmachtigingen vereist. Zoals hierboven weergegeven, specificeert het regelbestand de host of hosts waarop een declaratieve netaanvraag van toepassing is.

Als u 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 gebruiksvoorbeeld in Manifest V2 was het gebruiken van de BeforeRequest -gebeurtenis om webaanvragen 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 aan de webRequest listener is doorgegeven. Merk op dat in dit voorbeeld het "action" object van het regelbestand een "redirect" veld bevat met de te retourneren URL 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 omleiden naast de hostmachtiging ook de machtiging "declarativeNetRequestWithHostAccess" vereist.

Als u 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

Om cookies in Manifest V2 te blokkeren, moeten de webaanvraagheaders worden onderschept voordat ze worden verzonden en moet een specifieke header worden verwijderd.

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. Dit keer is het actietype "modifyHeaders" . Het bestand accepteert een array van "requestHeaders" -objecten die de te wijzigen headers en hoe deze moeten worden gewijzigd, specificeren. Merk op dat het "condition" -object alleen een "resourceTypes" -array bevat. Het ondersteunt dezelfde waarden als de vorige voorbeelden.

Als u 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": [
    ""
  ]