Zastąp blokowanie detektorów żądań internetowych

Platforma Manifest V3 zmienia sposób, w jaki rozszerzenia obsługują modyfikowanie żądań sieciowych. Zamiast przechwytywać żądania sieciowe i zmieniać je w czasie działania za pomocą chrome.webRequest, rozszerzenie określa reguły opisujące działania, które mają być wykonywane po spełnieniu danego zestawu warunków. Możesz to zrobić za pomocą interfejsu Declarative Net Request API.

Interfejs Web Request API i interfejs Declarative Net Request API znacznie się od siebie różnią. Zamiast zastępować jedno wywołanie funkcji innym, musisz przepisać kod pod kątem przypadków użycia. W tej sekcji znajdziesz opis tego procesu.

Jeśli rozszerzenie jest instalowane zgodnie z zasadami, nie musisz wprowadzać tych zmian. W przypadku rozszerzeń zainstalowanych zgodnie z zasadami uprawnienie webRequestBlocking jest nadal dostępne w platformie Manifest V3.

To druga z 3 sekcji opisujących zmiany, które należy wprowadzić w kodzie, który nie jest częścią procesu roboczego usługi rozszerzenia. Opisuje on przekształcanie blokujących żądań internetowych, które są używane w platformie Manifest V2, w deklaratywne żądania sieciowe, które są używane w platformie Manifest V3. Pozostałe 2 sekcje dotyczą aktualizacji kodu wymaganej do przejścia na platformę Manifest V3 i zwiększania bezpieczeństwa.

Wprowadzenie

W przypadku platformy Manifest V2 blokowanie żądań internetowych mogło znacznie obniżyć wydajność rozszerzeń i stron, z którymi współpracują. webRequestPrzestrzeń nazw obsługuje 9 zdarzeń, które mogą blokować inne zdarzenia. Każde z nich może mieć nieograniczoną liczbę funkcji obsługi zdarzeń. Co gorsza, każda strona internetowa może być blokowana przez wiele rozszerzeń, a wymagane do tego uprawnienia są inwazyjne. Manifest V3 zapobiega temu problemowi, zastępując wywołania zwrotne regułami deklaratywnymi.

Zmień uprawnienia

Wprowadź te zmiany w polu "permissions" w pliku manifest.json.

  • Usuń uprawnienie "webRequest", jeśli nie musisz już obserwować żądań sieciowych.
  • Przenieś wzorce dopasowania z "permissions" do "host_permissions".

W zależności od potrzeb musisz dodać inne uprawnienia. Te uprawnienia są opisane w kontekście przypadków użycia, które obsługują.

Tworzenie reguł deklaratywnych żądań sieciowych

Tworzenie reguł deklaratywnych żądań sieciowych wymaga dodania obiektu "declarative_net_request" do pliku manifest.json. Blok "declarative_net_request" zawiera tablicę obiektów "rule_resource", które wskazują plik reguł. Plik reguł zawiera tablicę obiektów określających działanie i warunki, w których te działania są wywoływane.

Częste przypadki użycia

W kolejnych sekcjach opisujemy typowe przypadki użycia deklaratywnych żądań sieciowych. Poniższe instrukcje zawierają tylko krótki zarys. Więcej informacji o wszystkich tych danych znajdziesz w dokumentacji interfejsu API w sekcji chrome.declarativeNetRequest.

Blokowanie pojedynczego adresu URL

W przypadku platformy Manifest V2 częstym zastosowaniem było blokowanie żądań internetowych za pomocą zdarzenia onBeforeRequest w skrypcie działającym w tle.

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

W przypadku Manifestu V3 utwórz nową regułę declarativeNetRequest, używając typu działania "block". Zwróć uwagę na obiekt "condition" w przykładowej regule. Jego wartość "urlFilter" zastępuje opcję urls przekazaną do odbiornika webRequest. Tablica "resourceTypes" określa kategorię zasobów do zablokowania. Ten przykład blokuje tylko główną stronę HTML, ale możesz na przykład blokować tylko czcionki.

Plik reguł platformy Manifest V3
[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

Aby to działało, musisz zaktualizować uprawnienia rozszerzenia. W manifest.json zastąp uprawnienie "webRequestBlocking" uprawnieniem "declarativeNetRequest". Zwróć uwagę, że adres URL został usunięty z pola "permissions", ponieważ blokowanie treści nie wymaga uprawnień hosta. Jak widać powyżej, plik reguł określa hosta lub hostów, do których ma zastosowanie deklaratywne żądanie sieciowe.

Jeśli chcesz to wypróbować, kod poniżej jest dostępny w naszym repozytorium z przykładami.

(platforma) Manifest V2
  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]
(platforma) Manifest V3
  "permissions": [
    "declarativeNetRequest",
  ]

Przekierowywanie wielu adresów URL

Innym typowym zastosowaniem w przypadku platformy Manifest V2 było używanie zdarzenia BeforeRequest do przekierowywania żądań internetowych.

Skrypt działający w tle na platformie Manifest V2
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"]
);

W przypadku pliku manifestu w wersji 3 użyj typu działania "redirect". Podobnie jak wcześniej, "urlFilter" zastępuje opcję url przekazaną do odbiorcy webRequest. Zauważ, że w tym przykładzie obiekt "action" w pliku reguł zawiera pole "redirect" z adresem URL, który ma być zwracany zamiast filtrowanego adresu URL.

Plik reguł platformy Manifest V3
[
  {
    "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"]
    }
  }
]

W tym scenariuszu konieczne są też zmiany uprawnień rozszerzenia. Podobnie jak wcześniej zastąp uprawnienie "webRequestBlocking" uprawnieniem "declarativeNetRequest". Adresy URL zostaną ponownie przeniesione z manifest.json do pliku reguł. Pamiętaj, że przekierowanie wymaga też uprawnienia "declarativeNetRequestWithHostAccess" oprócz uprawnienia dotyczącego hosta.

Jeśli chcesz to wypróbować, kod poniżej jest dostępny w naszym repozytorium z przykładami.

(platforma) Manifest V2
  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]
(platforma) Manifest V3
  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

Blokowanie plików cookie

W przypadku Manifestu V2 blokowanie plików cookie wymaga przechwycenia nagłówków żądań internetowych przed ich wysłaniem i usunięcia konkretnego nagłówka.

Skrypt działający w tle na platformie Manifest V2
chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    removeHeader(details.requestHeaders, 'cookie');
    return {requestHeaders: details.requestHeaders};
  },
  // filters
  {urls: ['https://*/*', 'http://*/*']},
  // extraInfoSpec
  ['blocking', 'requestHeaders', 'extraHeaders']);

Platforma Manifest V3 robi to również za pomocą reguły w pliku reguł. Tym razem typ działania to "modifyHeaders". Plik przyjmuje tablicę obiektów "requestHeaders" określających nagłówki do zmodyfikowania i sposób ich modyfikacji. Zwróć uwagę, że obiekt "condition" zawiera tylko tablicę "resourceTypes". Obsługuje te same wartości co w poprzednich przykładach.

Jeśli chcesz to wypróbować, kod poniżej jest dostępny w naszym repozytorium z przykładami.

plik manifestu manifest.json w platformie Manifest V3,
[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "cookie", "operation": "remove" }
      ]
    },
    "condition": {
      "urlFilter": "|*?no-cookies=1",
      "resourceTypes": ["main_frame"]
    }
  }
]

W tym scenariuszu konieczne są też zmiany uprawnień rozszerzenia. Podobnie jak wcześniej zastąp uprawnienie "webRequestBlocking" uprawnieniem "declarativeNetRequest".

(platforma) Manifest V2
  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "https://*/*",
    "http://*/*"
  ],
(platforma) Manifest V3
  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]