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

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ą browser.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 w kontekście 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 na platformie Manifest V3.

To druga z 3 sekcji opisujących zmiany, które należy wprowadzić w kodzie, który nie jest częścią skryptu service worker rozszerzenia. Opisuje on przekształcanie blokujących żądań internetowych używanych przez platformę Manifest V2 na deklaratywne żądania sieciowe używane przez platformę Manifest V3. W pozostałych 2 sekcjach znajdziesz informacje o aktualizacji kodu wymaganej do przejścia na platformę Manifest V3 oraz o zwiększaniu 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ć działanie innych funkcji. 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 deklaratywnych reguł żą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 sekcjach poniżej opisujemy typowe przypadki użycia deklaratywnych żądań sieciowych. Poniższe instrukcje zawierają tylko krótki opis. Więcej informacji o wszystkich tych danych znajdziesz w dokumentacji interfejsu API w sekcji browser.declarativeNetRequest.

Blokowanie pojedynczego adresu URL

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

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

W przypadku platformy Manifest 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 przekazywaną do odbiornika webRequest. Tablica "resourceTypes" określa kategorię zasobów do zablokowania. W tym przykładzie blokowana jest tylko główna strona HTML, ale możesz na przykład blokować tylko czcionki.

Plik reguł 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 tła platformy Manifest V2
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"]
);

W przypadku platformy Manifest V3 użyj "redirect"typu działania. Podobnie jak wcześniej, "urlFilter" zastępuje opcję url przekazywaną do odbiornika 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ł 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"]
    }
  }
]

Ten scenariusz wymaga też zmian w uprawnieniach rozszerzenia. Podobnie jak wcześniej zastąp uprawnienie "webRequestBlocking" uprawnieniem "declarativeNetRequest". Adresy URL są ponownie przenoszone z manifest.json do pliku reguł. Pamiętaj, że przekierowanie wymaga uprawnienia "declarativeNetRequestWithHostAccess" oprócz uprawnienia 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 (platformie) Manifest V2 blokowanie plików cookie wymaga przechwycenia nagłówków żądań sieciowych przed ich wysłaniem i usunięcia konkretnego nagłówka.

Skrypt tła platformy Manifest V2
browser.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 manifest.json platformy Manifest V3
[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "cookie", "operation": "remove" }
      ]
    },
    "condition": {
      "urlFilter": "|*?no-cookies=1",
      "resourceTypes": ["main_frame"]
    }
  }
]

Ten scenariusz wymaga też zmian w uprawnieniach 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": [
    ""
  ]