Reemplaza los objetos de escucha de solicitudes web de bloqueo

Manifest V3 cambia la forma en que las extensiones controlan la modificación de las solicitudes de red. En lugar de interceptar solicitudes de red y modificarlas en el tiempo de ejecución con chrome.webRequest, tu extensión especifica reglas que describen las acciones que se deben realizar cuando se cumple un conjunto determinado de condiciones. Para ello, usa la API de Declarative Net Request.

La API de Web Request y la API de Declarative Net Request son muy diferentes. En lugar de reemplazar una llamada a una función por otra, debes volver a escribir tu código en términos de casos de uso. En esta sección, se explica ese proceso.

No es necesario que realices estos cambios si la extensión se instala por política. En el caso de las extensiones instaladas por políticas, el permiso webRequestBlocking sigue disponible en Manifest V3.

Esta es la segunda de tres secciones que describen los cambios necesarios para el código que no forma parte del service worker de la extensión. Describe la conversión de solicitudes web de bloqueo, que usa Manifest V2, a solicitudes de red declarativas, que usa Manifest V3. Las otras dos secciones abarcan la actualización del código necesaria para migrar a Manifest V3 y la mejora de la seguridad.

Introducción

En Manifest V2, bloquear solicitudes web podía degradar significativamente el rendimiento de las extensiones y el de las páginas con las que trabajaban. El espacio de nombres webRequest admite nueve eventos potencialmente bloqueadores, cada uno de los cuales admite una cantidad ilimitada de controladores de eventos. Para empeorar las cosas, cada página web puede estar bloqueada por varias extensiones, y los permisos necesarios para esto son invasivos. Manifest V3 protege contra este problema reemplazando las devoluciones de llamada por reglas declarativas.

Actualizar permisos

Realiza los siguientes cambios en el campo "permissions" de tu manifest.json.

• Quita el permiso "webRequest" si ya no necesitas observar las solicitudes de red.
• Mueve los patrones de coincidencias de "permissions" a "host_permissions".

Deberás agregar otros permisos, según tu caso de uso. Esos permisos se describen con el caso de uso que admiten.

Cómo crear reglas de solicitudes de red declarativas

Para crear reglas de solicitud de red declarativas, debes agregar un objeto "declarative_net_request" a tu manifest.json. El bloque "declarative_net_request" contiene un array de objetos "rule_resource" que apuntan a un archivo de reglas. El archivo de reglas contiene un array de objetos que especifican una acción y las condiciones en las que se invoca esa acción.

Casos de uso habituales

En las siguientes secciones, se describen casos de uso comunes para las solicitudes de red declarativas. Las siguientes instrucciones solo proporcionan un breve esquema. En la referencia de la API, en chrome.declarativeNetRequest, se describe más información sobre todo lo que se menciona aquí.

Cómo bloquear una sola URL

En Manifest V2, un caso de uso común era bloquear solicitudes web con el evento onBeforeRequest en la secuencia de comandos en segundo plano.

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

Para Manifest V3, crea una regla declarativeNetRequest nueva con el tipo de acción "block". Observa el objeto "condition" en la regla de ejemplo. Su "urlFilter" reemplaza la opción urls que se pasa al objeto de escucha webRequest. Un array "resourceTypes" especifica la categoría de recursos que se bloquearán. En este ejemplo, se bloquea solo la página HTML principal, pero, por ejemplo, podrías bloquear solo las fuentes.

[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

Para que esto funcione, deberás actualizar los permisos de la extensión. En manifest.json, reemplaza el permiso "webRequestBlocking" por el permiso "declarativeNetRequest". Observa que la URL se quitó del campo "permissions" porque bloquear contenido no requiere permisos de host. Como se muestra arriba, el archivo de reglas especifica el host o los hosts a los que se aplica una solicitud de red declarativa.

Si quieres probarlo, el siguiente código está disponible en nuestro repositorio de muestras.

  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]

  "permissions": [
    "declarativeNetRequest",
  ]

Redirecciona varias URLs

Otro caso de uso común en Manifest V2 era usar el evento BeforeRequest para redireccionar solicitudes 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 Manifest V3, usa el tipo de acción "redirect". Al igual que antes, "urlFilter" reemplaza la opción url que se pasa al objeto de escucha webRequest. Ten en cuenta que, en este ejemplo, el objeto "action" del archivo de reglas contiene un campo "redirect" que incluye la URL que se devolverá en lugar de la URL que se filtra.

[
  {
    "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"]
    }
  }
]

Este caso también requiere cambios en los permisos de la extensión. Como antes, reemplaza el permiso "webRequestBlocking" por el permiso "declarativeNetRequest". Las URLs se vuelven a mover del archivo manifest.json a un archivo de reglas. Ten en cuenta que el redireccionamiento también requiere el permiso "declarativeNetRequestWithHostAccess", además del permiso de host.

Si quieres probarlo, el siguiente código está disponible en nuestro repositorio de muestras.

  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]

  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

Cómo bloquear cookies

En Manifest V2, bloquear las cookies requiere interceptar los encabezados de la solicitud web antes de que se envíen y quitar uno específico.

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

Manifest V3 también lo hace con una regla en un archivo de reglas. En esta ocasión, el tipo de acción es "modifyHeaders". El archivo toma un array de objetos "requestHeaders" que especifican los encabezados que se modificarán y cómo se modificarán. Ten en cuenta que el objeto "condition" solo contiene un array "resourceTypes". Admite los mismos valores que los ejemplos anteriores.

Si quieres probarlo, el siguiente código está disponible en nuestro repositorio de muestras.

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

Este caso también requiere cambios en los permisos de la extensión. Como antes, reemplaza el permiso "webRequestBlocking" por el permiso "declarativeNetRequest".

  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "https://*/*",
    "http://*/*"
  ],

  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]