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 browser.webRequest , specificeert uw extensie regels die acties beschrijven die moeten worden uitgevoerd wanneer aan een bepaalde set voorwaarden wordt voldaan. Doe dit met behulp van de Declarative Net Request API .

De Web Request API en de Declarative Net Request API's verschillen aanzienlijk van elkaar. In plaats van de ene functieaanroep door de andere te vervangen, moet u uw code herschrijven op basis van de gebruiksscenario's. In dit gedeelte wordt dat proces stap voor stap uitgelegd.

U hoeft deze wijzigingen niet door te voeren als uw extensie via beleid is geïnstalleerd. Voor via beleid geïnstalleerde extensies is de machtiging webRequestBlocking nog steeds beschikbaar in Manifest V3.

Dit is het tweede van drie delen waarin de wijzigingen worden beschreven die nodig zijn voor code die geen deel uitmaakt van de extension service worker. Het beschrijft de conversie van blokkerende webverzoeken, gebruikt door Manifest V2, naar declaratieve netwerkverzoeken, gebruikt door Manifest V3. De andere twee delen 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 kon het blokkeren van webverzoeken de prestaties van extensies en de pagina's waarmee ze werkten aanzienlijk verslechteren. De namespace webRequest ondersteunde negen potentieel blokkerende gebeurtenissen, die elk een onbeperkt aantal gebeurtenishandlers konden hebben. Bovendien kon elke webpagina potentieel door meerdere extensies worden geblokkeerd, en de daarvoor benodigde machtigingen waren ingrijpend. Manifest V3 lost dit probleem op door callbacks te vervangen door declaratieve regels.

Machtigingen bijwerken

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

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

Afhankelijk van uw gebruikssituatie moet u mogelijk andere machtigingen toevoegen. Deze machtigingen worden beschreven in samenhang met de gebruikssituatie die ze ondersteunen.

Maak declaratieve netwerkverzoekregels aan.

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

Veelvoorkomende gebruiksscenario's

De volgende secties beschrijven veelvoorkomende gebruiksscenario's voor declaratieve netwerkverzoeken. De onderstaande instructies geven slechts een beknopt overzicht. Meer informatie over alles wat hier wordt beschreven, is te vinden in de API-referentie onder browser.declarativeNetRequest

Blokkeer één enkele URL

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

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

Voor Manifest V3 maakt u een nieuwe declarativeNetRequest -regel aan met het actietype "block" . Let op het object "condition" in de voorbeeldregel. De "urlFilter" ervan vervangt de urls optie die aan de webRequest listener wordt doorgegeven. Een array "resourceTypes" specificeert de categorie van resources die moeten worden geblokkeerd. Dit voorbeeld blokkeert alleen de hoofd-HTML-pagina, maar u zou bijvoorbeeld ook alleen lettertypen kunnen blokkeren.

[
  {
    "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 het 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(s) waarop een declaratieve netwerkaanvraag van toepassing is.

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

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

  "permissions": [
    "declarativeNetRequest",
  ]

Meerdere URL's doorverwijzen

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

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

Voor Manifest V3 gebruikt u het actietype "redirect" . Net als voorheen vervangt "urlFilter" de url optie die aan de webRequest listener wordt doorgegeven. Merk op dat in 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.

[
  {
    "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 eerder, de machtiging "webRequestBlocking" door de machtiging "declarativeNetRequest" . De URL's worden opnieuw verplaatst van het manifest.json bestand naar een regelbestand. Merk op dat voor het omleiden naast de hostmachtiging ook de machtiging "declarativeNetRequestWithHostAccess" vereist is.

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

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

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

Blokkeer cookies

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

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

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

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

Ook in dit scenario zijn wijzigingen in de machtigingen van de extensie nodig. Vervang, net als eerder, de machtiging "webRequestBlocking" door de machtiging "declarativeNetRequest" .

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

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

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 browser.webRequest , specificeert uw extensie regels die acties beschrijven die moeten worden uitgevoerd wanneer aan een bepaalde set voorwaarden wordt voldaan. Doe dit met behulp van de Declarative Net Request API .

De Web Request API en de Declarative Net Request API's verschillen aanzienlijk van elkaar. In plaats van de ene functieaanroep door de andere te vervangen, moet u uw code herschrijven op basis van de gebruiksscenario's. In dit gedeelte wordt dat proces stap voor stap uitgelegd.

U hoeft deze wijzigingen niet door te voeren als uw extensie via beleid is geïnstalleerd. Voor via beleid geïnstalleerde extensies is de machtiging webRequestBlocking nog steeds beschikbaar in Manifest V3.

Dit is het tweede van drie delen waarin de wijzigingen worden beschreven die nodig zijn voor code die geen deel uitmaakt van de extension service worker. Het beschrijft de conversie van blokkerende webverzoeken, gebruikt door Manifest V2, naar declaratieve netwerkverzoeken, gebruikt door Manifest V3. De andere twee delen 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 kon het blokkeren van webverzoeken de prestaties van extensies en de pagina's waarmee ze werkten aanzienlijk verslechteren. De namespace webRequest ondersteunde negen potentieel blokkerende gebeurtenissen, die elk een onbeperkt aantal gebeurtenishandlers konden hebben. Bovendien kon elke webpagina potentieel door meerdere extensies worden geblokkeerd, en de daarvoor benodigde machtigingen waren ingrijpend. Manifest V3 lost dit probleem op door callbacks te vervangen door declaratieve regels.

Machtigingen bijwerken

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

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

Afhankelijk van uw gebruikssituatie moet u mogelijk andere machtigingen toevoegen. Deze machtigingen worden beschreven in samenhang met de gebruikssituatie die ze ondersteunen.

Maak declaratieve netwerkverzoekregels aan.

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

Veelvoorkomende gebruiksscenario's

De volgende secties beschrijven veelvoorkomende gebruiksscenario's voor declaratieve netwerkverzoeken. De onderstaande instructies geven slechts een beknopt overzicht. Meer informatie over alles wat hier wordt beschreven, is te vinden in de API-referentie onder browser.declarativeNetRequest

Blokkeer één enkele URL

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

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

Voor Manifest V3 maakt u een nieuwe declarativeNetRequest -regel aan met het actietype "block" . Let op het object "condition" in de voorbeeldregel. De "urlFilter" ervan vervangt de urls optie die aan de webRequest listener wordt doorgegeven. Een array "resourceTypes" specificeert de categorie van resources die moeten worden geblokkeerd. Dit voorbeeld blokkeert alleen de hoofd-HTML-pagina, maar u zou bijvoorbeeld ook alleen lettertypen kunnen blokkeren.

[
  {
    "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 het 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(s) waarop een declaratieve netwerkaanvraag van toepassing is.

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

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

  "permissions": [
    "declarativeNetRequest",
  ]

Meerdere URL's doorverwijzen

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

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

Voor Manifest V3 gebruikt u het actietype "redirect" . Net als voorheen vervangt "urlFilter" de url optie die aan de webRequest listener wordt doorgegeven. Merk op dat in 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.

[
  {
    "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 eerder, de machtiging "webRequestBlocking" door de machtiging "declarativeNetRequest" . De URL's worden opnieuw verplaatst van het manifest.json bestand naar een regelbestand. Merk op dat voor het omleiden naast de hostmachtiging ook de machtiging "declarativeNetRequestWithHostAccess" vereist is.

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

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

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

Blokkeer cookies

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

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

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

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

Ook in dit scenario zijn wijzigingen in de machtigingen van de extensie nodig. Vervang, net als eerder, de machtiging "webRequestBlocking" door de machtiging "declarativeNetRequest" .

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

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