Como modificar solicitações de rede no Manifest V3
O Manifesto V3 muda a forma como as extensões processam a modificação de solicitações de rede. Em vez de interceptar e alterar solicitações de rede no momento da execução com chrome.webRequest, a 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 Declarativa de solicitação de rede.
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.
No Manifest V2, o bloqueio de solicitações da Web poderia 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 protege contra esse problema substituindo callbacks por regras declarativas.
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 worker de serviço 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.
Atualizar permissões
Faça as seguintes mudanças no campo "permissions" do manifest.json.
- Remova a permissão
"webRequest"se você não precisar mais observar as solicitações de rede. - Mova os padrões de correspondência de
"permissions"para"host_permissions".
Dependendo do caso de uso, será necessário adicionar outras permissões. Essas permissões são descritas com o caso de uso que elas suportam.
Criar regras declarativas de solicitação de rede
Para criar regras declarativas de solicitação de rede, adicione um objeto "declarative_net_request" ao manifest.json. O bloco "declarative_net_request" contém uma matriz de objetos "rule_resource" que apontam para um arquivo de regra. O arquivo de regra 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 são apenas um breve resumo. Mais informações sobre todas as informações aqui sã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.
chrome.webRequest.onBeforeRequest.addListener((e) => {
return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);
Para o Manifest V3, crie uma nova regra declarativeNetRequest usando o tipo de ação "block". Observe o objeto "condition" na regra de exemplo. O "urlFilter" substitui a opção urls transmitida ao listener webRequest. Uma matriz "resourceTypes" especifica a categoria de recursos a serem bloqueadas. Este exemplo bloqueia apenas a página HTML principal, mas você pode, por exemplo, bloquear apenas as fontes.
[
{
"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 permissão "declarativeNetRequest". O URL é removido do campo "permissions" porque o bloqueio de conteúdo não exige permissões do host. Como mostrado acima, o arquivo de regra especifica o host ou os hosts a que uma solicitação de rede declarativa se aplica.
Se você quiser testar isso, o código abaixo está disponível no nosso repositório de amostras.
"permissions": [
"webRequestBlocking",
"https://*.example.com/*"
]
"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.
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 regra contém um campo "redirect" com o URL a ser retornado em vez do URL filtrado.
[
{
"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 regra. O redirecionamento também requer a permissão "declarativeNetRequestWithHostAccess", além da permissão do host.
Se você quiser testar isso, o código abaixo está disponível no nosso repositório de amostras.
"permissions": [
"webRequestBlocking",
"https://developer.chrome.com/docs/extensions/*",
"https://developer.chrome.com/docs/extensions/reference"
]
"permissions": [
"declarativeNetRequestWithHostAccess"
],
"host_permissions": [
"https://developer.chrome.com/*"
]
Bloquear cookies
No Manifest V2, o bloqueio de cookies exige a interceptação dos cabeçalhos de solicitação da Web antes do envio e a remoção de um cabeçalho específico.
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 recebe uma matriz de objetos "requestHeaders" que especificam os cabeçalhos a serem modificados e como fazer isso. O objeto "condition" contém apenas uma matriz "resourceTypes". Ele aceita os mesmos valores dos exemplos anteriores.
Se você quiser testar isso, o código abaixo está disponível no nosso repositório de amostras.
[
{
"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".
"permissions": [
"webRequest",
"webRequestBlocking",
"https://*/*",
"http://*/*"
],
"permissions": [
"declarativeNetRequest",
],
"host_permissions": [
""
]