Manifest V3 ändert die Art und Weise, wie Erweiterungen die Änderung von Netzwerkanfragen verarbeiten. Anstatt Netzwerkanfragen abzufangen und sie zur Laufzeit mit browser.webRequest zu ändern, werden in Ihrer Erweiterung Regeln angegeben, die beschreiben, welche Aktionen ausgeführt werden sollen, wenn eine bestimmte Gruppe von Bedingungen erfüllt ist. Verwenden Sie dazu die Declarative Net Request API.
Die Web Request API und die Declarative Net Request APIs unterscheiden sich erheblich. Anstatt einen Funktionsaufruf durch einen anderen zu ersetzen, müssen Sie Ihren Code anhand von Anwendungsfällen neu schreiben. In diesem Abschnitt wird das Verfahren beschrieben.
Wenn Ihre Erweiterung durch eine Richtlinie installiert wird, müssen Sie diese Änderungen nicht vornehmen. Für richtlinienkonform installierte Erweiterungen ist die Berechtigung webRequestBlocking weiterhin in Manifest V3 verfügbar.
Dies ist der zweite von drei Abschnitten, in denen Änderungen beschrieben werden, die für Code erforderlich sind, der nicht Teil des Service Workers der Erweiterung ist. Darin wird beschrieben, wie blockierende Webanfragen, die von Manifest V2 verwendet werden, in deklarative Netzwerkanfragen umgewandelt werden, die von Manifest V3 verwendet werden. In den beiden anderen Abschnitten geht es um das Aktualisieren Ihres Codes für die Migration zu Manifest V3 und um die Verbesserung der Sicherheit.
Einführung
In Manifest V2 konnte das Blockieren von Webanfragen sowohl die Leistung von Erweiterungen als auch die Leistung von Seiten, mit denen sie zusammenarbeiten, erheblich beeinträchtigen. Der webRequest-Namespace unterstützt neun potenziell blockierende Ereignisse, für die jeweils eine unbegrenzte Anzahl von Event-Handlern verwendet werden kann. Erschwerend kommt hinzu, dass jede Webseite potenziell von mehreren Erweiterungen blockiert wird und die dafür erforderlichen Berechtigungen invasiv sind. Manifest V3 schützt vor diesem Problem, indem Callbacks durch deklarative Regeln ersetzt werden.
Berechtigungen aktualisieren
Nehmen Sie die folgenden Änderungen am Feld "permissions" in Ihrem manifest.json vor.
- Entfernen Sie die Berechtigung
"webRequest", wenn Sie keine Netzwerkanfragen mehr beobachten müssen. - Verschieben Sie die Muster für den Abgleich von
"permissions"nach"host_permissions".
Je nach Anwendungsfall müssen Sie weitere Berechtigungen hinzufügen. Diese Berechtigungen werden mit dem Anwendungsfall beschrieben, den sie unterstützen.
Regeln für deklarative Netzwerkanfragen erstellen
Zum Erstellen deklarativer Regeln für Netzwerkanfragen müssen Sie Ihrem manifest.json ein "declarative_net_request"-Objekt hinzufügen. Der "declarative_net_request"-Block enthält ein Array von "rule_resource"-Objekten, die auf eine Regeldatei verweisen. Die Regeldatei enthält ein Array von Objekten, in denen eine Aktion und die Bedingungen angegeben sind, unter denen diese Aktionen aufgerufen werden.
Gängige Anwendungsfälle
In den folgenden Abschnitten werden gängige Anwendungsfälle für deklarative Netzwerkanfragen beschrieben. Die folgende Anleitung bietet nur einen kurzen Überblick. Weitere Informationen zu allen hier beschriebenen Informationen finden Sie in der API-Referenz unter browser.declarativeNetRequest.
Einzelne URL blockieren
Ein häufiger Anwendungsfall in Manifest V2 war das Blockieren von Webanfragen mit dem onBeforeRequest-Ereignis im Hintergrundskript.
browser.webRequest.onBeforeRequest.addListener((e) => { return { cancel: true }; }, { urls: ["https://www.example.com/*"] }, ["blocking"]);
Erstellen Sie für Manifest V3 eine neue declarativeNetRequest-Regel mit dem Aktionstyp "block". Beachten Sie das "condition"-Objekt in der Beispielregel. Der "urlFilter"-Wert ersetzt die Option urls, die an den webRequest-Listener übergeben wird. Ein "resourceTypes"-Array gibt die Kategorie der zu blockierenden Ressourcen an. In diesem Beispiel wird nur die Haupt-HTML-Seite blockiert. Sie könnten aber beispielsweise auch nur Schriftarten blockieren.
[ { "id" : 1, "priority": 1, "action" : { "type" : "block" }, "condition" : { "urlFilter" : "||example.com", "resourceTypes" : ["main_frame"] } } ]
Dazu müssen Sie die Berechtigungen der Erweiterung aktualisieren. Ersetzen Sie in der manifest.json die Berechtigung "webRequestBlocking" durch die Berechtigung "declarativeNetRequest". Die URL wird aus dem Feld "permissions" entfernt, da zum Blockieren von Inhalten keine Hostberechtigungen erforderlich sind. Wie oben gezeigt, wird in der Regeldatei der Host oder die Hosts angegeben, für die eine deklarative Netzwerkanfrage gilt.
Wenn Sie das ausprobieren möchten, finden Sie den Code unten in unserem Beispiel-Repository.
"permissions": [ "webRequestBlocking", "https://*.example.com/*" ]
"permissions": [ "declarativeNetRequest", ]
Mehrere URLs weiterleiten
Ein weiterer häufiger Anwendungsfall in Manifest V2 war die Verwendung des BeforeRequest-Ereignisses zum Weiterleiten von Webanfragen.
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"] );
Verwenden Sie für Manifest V3 den Aktionstyp "redirect". Wie zuvor ersetzt "urlFilter" die Option url, die an den webRequest-Listener übergeben wird. Beachten Sie, dass das "action"-Objekt der Regeldatei in diesem Beispiel ein "redirect"-Feld mit der zurückzugebenden URL anstelle der gefilterten URL enthält.
[ { "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"] } } ]
Für dieses Szenario sind auch Änderungen an den Berechtigungen der Erweiterung erforderlich. Ersetzen Sie wie zuvor die Berechtigung "webRequestBlocking" durch die Berechtigung "declarativeNetRequest". Die URLs werden wieder aus der manifest.json in eine Regeldatei verschoben. Beachten Sie, dass für die Weiterleitung zusätzlich zur Hostberechtigung auch die Berechtigung "declarativeNetRequestWithHostAccess" erforderlich ist.
Wenn Sie das ausprobieren möchten, finden Sie den Code unten in unserem Beispiel-Repository.
"permissions": [ "webRequestBlocking", "https://developer.chrome.com/docs/extensions/*", "https://developer.chrome.com/docs/extensions/reference" ]
"permissions": [ "declarativeNetRequestWithHostAccess" ], "host_permissions": [ "https://developer.chrome.com/*" ]
Cookies blockieren
In Manifest V2 müssen Sie zum Blockieren von Cookies die Webanfrageheader abfangen, bevor sie gesendet werden, und einen bestimmten Header entfernen.
browser.webRequest.onBeforeSendHeaders.addListener( function(details) { removeHeader(details.requestHeaders, 'cookie'); return {requestHeaders: details.requestHeaders}; }, // filters {urls: ['https://*/*', 'http://*/*']}, // extraInfoSpec ['blocking', 'requestHeaders', 'extraHeaders']);
In Manifest V3 wird dies auch mit einer Regel in einer Regeldatei erreicht. Dieses Mal ist der Aktionstyp "modifyHeaders". Die Datei enthält ein Array von "requestHeaders"-Objekten, in denen die zu ändernden Header und die Art der Änderung angegeben werden. Das "condition"-Objekt enthält nur ein "resourceTypes"-Array. Es unterstützt dieselben Werte wie die vorherigen Beispiele.
Wenn Sie das ausprobieren möchten, finden Sie den Code unten in unserem Beispiel-Repository.
[ { "id": 1, "priority": 1, "action": { "type": "modifyHeaders", "requestHeaders": [ { "header": "cookie", "operation": "remove" } ] }, "condition": { "urlFilter": "|*?no-cookies=1", "resourceTypes": ["main_frame"] } } ]
Für dieses Szenario sind auch Änderungen an den Berechtigungen der Erweiterung erforderlich. Ersetzen Sie wie zuvor die Berechtigung "webRequestBlocking" durch die Berechtigung "declarativeNetRequest".
"permissions": [ "webRequest", "webRequestBlocking", "https://*/*", "http://*/*" ],
"permissions": [ "declarativeNetRequest", ], "host_permissions": [ "" ]