Manifest V3 ändert die Art und Weise, wie Erweiterungen die Änderung von Netzwerkanfragen verarbeiten. Anstatt Netzwerkanfragen abzufangen und sie zur Laufzeit mit chrome.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 dieser Prozess beschrieben.
Sie müssen diese Änderungen nicht vornehmen, wenn Ihre Erweiterung per Richtlinie installiert wird. 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 in Ihrer manifest.json die folgenden Änderungen am Feld "permissions" vor.
- Entfernen Sie die Berechtigung
"webRequest", wenn Sie keine Netzwerk-Anfragen 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 zusammen 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 häufige 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 chrome.declarativeNetRequest.
Einzelne URL blockieren
Ein häufiger Anwendungsfall in Manifest V2 war das Blockieren von Webanfragen mit dem onBeforeRequest-Ereignis im Hintergrundskript.
chrome.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 Objekt "condition" 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 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.
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"] );
Verwenden Sie für Manifest V3 den Aktionstyp "redirect". Wie bisher 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 zum Blockieren von Cookies die Webanfrageheader abgefangen werden, bevor sie gesendet werden, und ein bestimmter Header muss entfernt werden.
chrome.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. Beachten Sie, dass das "condition"-Objekt nur ein "resourceTypes"-Array enthält. Es werden dieselben Werte wie in den vorherigen Beispielen unterstützt.
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": [ "" ]