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

Изменение сетевых запросов в Манифесте V3

Манифест V3 меняет способ обработки расширений модификацией сетевых запросов. Вместо перехвата сетевых запросов и изменения их во время выполнения с помощью chrome.webRequest ваше расширение определяет правила, описывающие действия, которые необходимо выполнить при выполнении заданного набора условий. Сделайте это с помощью API Declarative Net Request .

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

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

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

Обновить разрешения

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

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

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

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

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

Распространенные случаи использования

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

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

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

Фоновый сценарий манифеста V2
chrome.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

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

Файл правил манифеста 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 для перенаправления веб-запросов.

Фоновый сценарий манифеста 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"]
);

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

Файл правил манифеста 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

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

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

Манифест 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": [
    ""
  ]