Заменить блокирующие прослушиватели веб-запросов

Manifest V3 меняет подход расширений к обработке изменений сетевых запросов. Вместо перехвата сетевых запросов и их изменения во время выполнения с помощью browser.webRequest , ваше расширение задаёт правила, описывающие действия, которые необходимо выполнить при выполнении определённого набора условий. Это можно сделать с помощью декларативного API сетевых запросов .

API веб-запросов и декларативный API сетевых запросов существенно отличаются. Вместо замены одного вызова функции другим, вам необходимо переписать свой код с учетом вариантов использования. В этом разделе описан этот процесс.

Если ваше расширение установлено с помощью политики, вносить эти изменения не требуется. Для расширений, установленных с помощью политики, разрешение webRequestBlocking по-прежнему доступно в Manifest V3.

Это второй из трех разделов, описывающих изменения, необходимые для кода, не являющегося частью сервисного обработчика расширений. В нем описывается преобразование блокирующих веб-запросов, используемых Manifest V2, в декларативные сетевые запросы, используемые Manifest V3. Два других раздела посвящены обновлению кода, необходимого для миграции на Manifest V3, и повышению безопасности .

Введение

В Manifest V2 блокировка веб-запросов могла значительно ухудшить как производительность расширений, так и производительность страниц, с которыми они работают. Пространство имен webRequest поддерживает девять потенциально блокирующих событий, каждое из которых принимает неограниченное количество обработчиков событий. Что еще хуже, каждая веб-страница потенциально может быть заблокирована несколькими расширениями, а необходимые для этого разрешения являются инвазивными. Manifest V3 защищает от этой проблемы, заменяя коллбэки декларативными правилами.

Обновить права доступа

Внесите следующие изменения в поле "permissions" в вашем manifest.json .

  • Удалите разрешение "webRequest" , если вам больше не нужно отслеживать сетевые запросы.
  • Переместите параметры Match Patterns из раздела "permissions" в раздел "host_permissions" .

В зависимости от конкретного сценария использования вам потребуется добавить и другие разрешения. Эти разрешения описаны в соответствии с поддерживаемым ими сценарием использования.

Создайте декларативные правила сетевых запросов.

Для создания декларативных правил сетевых запросов необходимо добавить объект "declarative_net_request" в файл manifest.json . Блок "declarative_net_request" содержит массив объектов "rule_resource" , указывающих на файл правил. Файл правил содержит массив объектов, определяющих действие и условия, при которых эти действия выполняются.

Типичные сценарии использования

В следующих разделах описаны типичные сценарии использования запросов DeclarativeNetRequest. Приведенные ниже инструкции представляют собой лишь краткое описание. Более подробная информация обо всем вышеизложенном описана в справочнике API по адресу browser.declarativeNetRequest

Заблокировать один URL-адрес

В Manifest V2 часто использовался сценарий блокировки веб-запросов с помощью события onBeforeRequest в фоновом скрипте.

Фоновый скрипт Manifest V2 
browser.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

Для Manifest V3 создайте новое правило declarativeNetRequest , используя тип действия "block" . Обратите внимание на объект "condition" в примере правила. Его "urlFilter" заменяет параметр urls , передаваемый обработчику webRequest . Массив "resourceTypes" указывает категорию ресурсов для блокировки. В этом примере блокируется только основная HTML-страница, но вы можете, например, заблокировать только шрифты.

Файл правил Manifest V3 
[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

Для этого вам потребуется обновить права доступа расширения. В файле manifest.json замените разрешение "webRequestBlocking" на разрешение "declarativeNetRequest" . Обратите внимание, что URL-адрес удален из поля "permissions" поскольку блокировка контента не требует прав доступа к хосту. Как показано выше, файл правил указывает хост или хосты, к которым применяется декларативный сетевой запрос.

Если вы хотите попробовать это, приведенный ниже код доступен в нашем репозитории с примерами .

Манифест V2 
  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]
Манифест V3 
  "permissions": [
    "declarativeNetRequest",
  ]

Перенаправление нескольких URL-адресов

Еще одним распространенным вариантом использования Manifest V2 было применение события BeforeRequest для перенаправления веб-запросов.

Фоновый скрипт 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"]
);

Для Manifest V3 используйте тип действия "redirect" . Как и прежде, "urlFilter" заменяет параметр url , передаваемый обработчику webRequest . Обратите внимание, что в этом примере объект "action" файла правил содержит поле "redirect" содержащее URL-адрес для возврата вместо URL-адреса, подлежащего фильтрации.

Файл правил 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"]
    }
  }
]

Этот сценарий также требует изменения разрешений расширения. Как и прежде, замените разрешение "webRequestBlocking" на разрешение "declarativeNetRequest" . URL-адреса снова перемещаются из manifest.json в файл правил. Обратите внимание, что для перенаправления, помимо разрешения хоста, также требуется разрешение "declarativeNetRequestWithHostAccess" .

Если вы хотите попробовать это, приведенный ниже код доступен в нашем репозитории с примерами .

Манифест V2 
  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]
Манифест V3 
  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

Блокировка файлов cookie

В Manifest V2 блокировка файлов cookie требует перехвата заголовков веб-запроса до их отправки и удаления определенного из них.

Фоновый скрипт Manifest V2 
browser.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    removeHeader(details.requestHeaders, 'cookie');
    return {requestHeaders: details.requestHeaders};
  },
  // filters
  {urls: ['https://*/*', 'http://*/*']},
  // extraInfoSpec
  ['blocking', 'requestHeaders', 'extraHeaders']);

В Manifest V3 это также реализовано с помощью правила в файле правил. На этот раз тип действия — "modifyHeaders" . Файл принимает массив объектов "requestHeaders" , указывающих заголовки для изменения и способ их изменения. Обратите внимание, что объект "condition" содержит только массив "resourceTypes" . Он поддерживает те же значения, что и в предыдущих примерах.

Если вы хотите попробовать это, приведенный ниже код доступен в нашем репозитории с примерами .

Манифест V3 manifest.json 
[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "cookie", "operation": "remove" }
      ]
    },
    "condition": {
      "urlFilter": "|*?no-cookies=1",
      "resourceTypes": ["main_frame"]
    }
  }
]

Этот сценарий также требует изменения разрешений расширения. Как и прежде, замените разрешение "webRequestBlocking" на разрешение "declarativeNetRequest" .

Манифест V2 
  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "https://*/*",
    "http://*/*"
  ],
Манифест V3 
  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]