Substituir listeners de solicitações da Web bloqueados

O Manifesto V3 muda a forma como as extensões lidam com a modificação de solicitações de rede. Em vez de interceptar solicitações de rede e alterá-las durante a execução com chrome.webRequest, sua extensão especifica regras que descrevem as ações a serem realizadas quando um determinado conjunto de condições é atendido. Faça isso usando a API Declarative Net Request.

A API Web Request e as APIs Declarative Net Request são significativamente diferentes. Em vez de substituir uma chamada de função por outra, você precisa reescrever o código em termos de casos de uso. Esta seção explica esse processo.

Não é necessário fazer essas mudanças se a extensão for instalada por política. Para extensões instaladas por política, a permissão webRequestBlocking ainda está disponível no Manifesto V3.

Esta é a segunda de três seções que descrevem as mudanças necessárias para o código que não faz parte do service worker da extensão. Ele descreve a conversão de solicitações da Web de bloqueio, usadas pelo Manifest V2, em solicitações de rede declarativas, usadas pelo Manifest V3. As outras duas seções abordam a atualização do código necessária para migrar para o Manifest V3 e a melhoria da segurança.

Introdução

No Manifest V2, o bloqueio de solicitações da Web pode prejudicar significativamente a performance das extensões e das páginas com que elas trabalham. O namespace webRequest aceita nove eventos potencialmente bloqueadores, cada um com um número ilimitado de manipuladores de eventos. Para piorar, cada página da Web pode ser bloqueada por várias extensões, e as permissões necessárias para isso são invasivas. O Manifest V3 evita esse problema substituindo os callbacks por regras declarativas.

Atualizar permissões

Faça as seguintes mudanças no campo "permissions" do seu manifest.json.

  • Remova a permissão "webRequest" se você não precisar mais observar solicitações de rede.
  • Mova os padrões de correspondência de "permissions" para "host_permissions".

Você precisará adicionar outras permissões, dependendo do seu caso de uso. Essas permissões são descritas com o caso de uso que elas oferecem suporte.

Criar regras de solicitação de rede declarativa

Para criar regras declarativas de solicitação de rede, é necessário adicionar um objeto "declarative_net_request" ao seu manifest.json. O bloco "declarative_net_request" contém uma matriz de objetos "rule_resource" que apontam para um arquivo de regras. O arquivo de regras contém uma matriz de objetos que especificam uma ação e as condições em que essas ações são invocadas.

Casos de uso comuns

As seções a seguir descrevem casos de uso comuns para solicitações de rede declarativas. As instruções abaixo fornecem apenas um breve resumo. Mais informações sobre tudo isso estão descritas na referência da API em chrome.declarativeNetRequest.

Bloquear um único URL

Um caso de uso comum no Manifest V2 era bloquear solicitações da Web usando o evento onBeforeRequest no script em segundo plano.

Script em segundo plano do Manifest V2
chrome.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

Para o Manifest V3, crie uma regra declarativeNetRequest usando o tipo de ação "block". Observe o objeto "condition" na regra de exemplo. O "urlFilter" dele substitui a opção urls transmitida ao listener webRequest. Uma matriz "resourceTypes" especifica a categoria de recursos a serem bloqueados. Este exemplo bloqueia apenas a página HTML principal, mas você pode, por exemplo, bloquear apenas fontes.

Arquivo de regras do Manifest V3
[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

Para isso, atualize as permissões da extensão. No manifest.json, substitua a permissão "webRequestBlocking" pela "declarativeNetRequest". O URL é removido do campo "permissions" porque o bloqueio de conteúdo não exige permissões de host. Como mostrado acima, o arquivo de regras especifica o host ou os hosts a que uma solicitação de rede declarativa se aplica.

Se quiser testar, o código abaixo está disponível no nosso repositório de exemplos.

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

Redirecionar vários URLs

Outro caso de uso comum no Manifest V2 era usar o evento BeforeRequest para redirecionar solicitações da Web.

Script em segundo plano do 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"]
);

Para o Manifest V3, use o tipo de ação "redirect". Como antes, "urlFilter" substitui a opção url transmitida ao listener webRequest. Neste exemplo, o objeto "action" do arquivo de regras contém um campo "redirect" com o URL a ser retornado em vez do URL filtrado.

Arquivo de regras do 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"]
    }
  }
]

Esse cenário também exige mudanças nas permissões da extensão. Como antes, substitua a permissão "webRequestBlocking" pela permissão "declarativeNetRequest". Os URLs são movidos novamente do manifest.json para um arquivo de regras. O redirecionamento também exige a permissão "declarativeNetRequestWithHostAccess", além da permissão do host.

Se quiser testar, o código abaixo está disponível no nosso repositório de exemplos.

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

Bloquear cookies

No Manifest V2, para bloquear cookies, é necessário interceptar os cabeçalhos de solicitação da Web antes do envio e remover um específico.

Script em segundo plano do Manifest V2
chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    removeHeader(details.requestHeaders, 'cookie');
    return {requestHeaders: details.requestHeaders};
  },
  // filters
  {urls: ['https://*/*', 'http://*/*']},
  // extraInfoSpec
  ['blocking', 'requestHeaders', 'extraHeaders']);

O Manifesto V3 também faz isso com uma regra em um arquivo de regras. Desta vez, o tipo de ação é "modifyHeaders". O arquivo usa uma matriz de objetos "requestHeaders" que especificam os cabeçalhos a serem modificados e como modificá-los. O objeto "condition" contém apenas uma matriz "resourceTypes". Ele aceita os mesmos valores dos exemplos anteriores.

Se quiser testar, o código abaixo está disponível no nosso repositório de exemplos.

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

Esse cenário também exige mudanças nas permissões da extensão. Como antes, substitua a permissão "webRequestBlocking" pela permissão "declarativeNetRequest".

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