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

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

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

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

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

Введение

В Manifest V2 блокировка веб-запросов может значительно снизить производительность как расширений, так и страниц, с которыми они работают. Пространство имён webRequest поддерживает девять потенциально блокирующих событий, каждое из которых требует неограниченного количества обработчиков событий. Ситуация усугубляется тем, что каждая веб-страница потенциально блокируется несколькими расширениями, а требуемые для этого разрешения являются инвазивными. 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 в фоновом скрипте.

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

Для 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/*"
  ]

Блокировать куки

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

Фоновый скрипт Manifest V2 
chrome.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": [
    ""
  ]