Migra a la API de Reporting v1

Hay una nueva versión disponible de la API de Reporting. Es más privada y es más probable que sea compatible con todos los navegadores.

Maud Nalpas

Precaución: En esta publicación, se explica cómo migrar a la nueva versión de la API de Reporting (v1). Si es la primera vez que usas la API de Reporting o necesitas ejemplos de uso detallados, ve a la publicación principal de la API de Reporting.

La API de Reporting te informa sobre los errores que se producen en tu sitio a medida que los visitantes lo usan. Te brinda visibilidad sobre las intervenciones del navegador, las fallas del navegador, los incumplimientos de la Política de Seguridad del Contenido, los incumplimientos de COOP/COEP, las advertencias de baja y mucho más.

Hay una nueva versión de la API de Reporting disponible. La nueva API es más liviana y es más probable que sea compatible con todos los navegadores.

Nota: La API de Reporting heredada se denomina API de Reporting v0. La nueva API de Reporting se llama API de Reporting v1.

Resumen

Desarrolladores del sitio

Si ya tienes la función de informes para tu sitio, migra a la versión 1 con el encabezado nuevo (Reporting-Endpoints), pero mantén el encabezado heredado durante algún tiempo (Report-To). Consulta Migración: código de ejemplo.

Si estás agregando la funcionalidad de informes a tu sitio en este momento, usa solo el encabezado nuevo (Reporting-Endpoints).

⚠️ En ambos casos, asegúrate de configurar el encabezado Reporting-Endpoints en todas las respuestas que podrían generar informes.

Desarrolladores de servicios de informes

Si mantienes un servicio de extremo o operas el tuyo, espera más tráfico a medida que tú o los desarrolladores externos migran a la API de informes v1 (encabezado Reporting-Endpoints).

Sigue leyendo para conocer los detalles y el código de ejemplo.

Registro de errores de red

Precaución: Si usas Network Error Logging, continúa usando Report-To (v0) porque el registro de errores de red no es compatible con la versión 1 de la API de Reporting.

Se desarrollará un nuevo mecanismo para el registro de errores de red. Una vez que esté disponible, cambia de la versión 0 de la API de Reporting a ese nuevo mecanismo.

Demostración y código

• Sitio de demostración: nueva API de informes (v1)
• Código del sitio de demostración

Diferencias entre v0 y v1

Qué cambiará

• La plataforma de la API es diferente.

Versión 0 (heredada)

 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

{0 usa el encabezado Report-To para configurar grupos de extremos nombrados y la directiva report-to en otros encabezados para hacer referencia a estos grupos de extremos.

v1 (nuevo)

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

La versión 1 usa el encabezado Reporting-Endpoints para configurar endpoints nominados. Al igual que la versión 0, usa la directiva report-to en otros encabezados para hacer referencia a estos grupos de extremos.

• El alcance del informe es diferente.

Versión 0 (heredada)

Con la versión 0, puedes configurar extremos de informes solo en algunas respuestas. Otros documentos (páginas) de ese origen usarían automáticamente estos extremos ambientales.

v1 (nuevo)

Con la versión 1, debes configurar el encabezado Reporting-Endpoints en todas las respuestas que puedan generar informes.

• Ambas APIs admiten los mismos tipos de informes, con una excepción: la v1 no admite los informes de errores de red. Obtén más información en los pasos para la migración.
• v0 no es ni será compatible con todos los navegadores. Es más probable que v1 sea compatible con varios navegadores en el futuro.

Qué permanece sin cambios

• El formato y la estructura de los informes no cambian.
• La solicitud enviada por el navegador al extremo sigue siendo una solicitud POST de Content-type application/reports+json.
• La v0 y la v1 admiten la asignación de ciertos extremos a ciertos tipos de informes.
• El rol del extremo default no cambia.

• La versión 1 de la API de Reporting no afecta a ReportingObserver. ReportingObserver sigue teniendo acceso a todos los informes observables, y su formato es idéntico.

Todas las diferencias entre v0 y v1

	API de informes heredada (v0) Header Report-To	Nueva API de informes (v1) Reporting-Endpoints encabezado
Navegadores compatibles	Chrome 69 y versiones posteriores, y Edge 69 y versiones posteriores	Chrome 96 y versiones posteriores, y Edge 96 y versiones posteriores. Firefox es compatible. Safari no se opone. Consulta los indicadores del navegador.
Extremos	Envía informes a cualquiera de los múltiples recopiladores de informes (múltiples URLs definidas por grupo de extremos).	Envía informes a colectores de informes específicos (solo una URL definida por extremo).
Superficie de la API	Usa el encabezado `Report-To` para configurar grupos de extremos nombrados.	Usa el encabezado `Reporting-Endpoints` para configurar extremos nombrados.
Tipos de informes que se pueden generar a través de esta API	Baja Intervención Choque COOP/COEP Content-Security-Policy nivel 3 (CSP nivel 3) Registro de errores de red (NEL) Obtén más información sobre los tipos de informes en la publicación API de Reporting.	Sin cambios, excepto en Network Error Logging (NEL): Esto no se admite en la nueva API de Reporting (v1).
Alcance del informe	origen. El encabezado Report-To de un documento afecta a otros documentos (páginas) de ese origen. El campo url de un informe varía según el documento.	Document. El encabezado Reporting-Endpoints de un documento solo afecta a ese documento. El campo url de un informe varía según el documento.
Aislamiento de informes (agrupación)	Los diferentes documentos (páginas) o sitios/origen que generen un informe aproximadamente al mismo tiempo y que tengan el mismo extremo de informes se agruparán en lotes: se enviarán en el mismo mensaje al extremo de informes.	Los informes de diferentes documentos (páginas) nunca se envían juntos. Incluso si dos documentos (páginas) del mismo origen generan un informe al mismo tiempo para el mismo extremo, no se agruparán. Este es un mecanismo para mitigar los ataques de privacidad. Los informes del mismo documento (página) se pueden enviar juntos.
Compatibilidad con el balanceo de cargas o las prioridades	Sí	No

Desarrolladores de extremos: Esperan más tráfico

Si configuraste tu propio servidor como un extremo de informes o si desarrollas o mantienes un recopilador de informes como un servicio, espera más tráfico hacia ese extremo.

Esto se debe a que los informes no se agrupan con la versión 1 de la API de Reporting, como lo hacen con la versión 0. Por lo tanto, a medida que los desarrolladores de aplicaciones comiencen a migrar a la versión 1 de la API de Reporting, la cantidad de informes seguirá siendo similar, pero aumentará el volumen de solicitudes al servidor de extremos.

Desarrolladores de aplicaciones: Migra a Reporting-Endpoints (v1)

¿Qué deberías hacer?

Usar la nueva API de Reporting (v1) tiene varios beneficios ✅:

• Los indicadores del navegador son positivos, lo que significa que se puede esperar compatibilidad multinavegador para la v1 (a diferencia de la v0, que solo es compatible con Chrome y Edge).
• La API es más liviana.
• Se están desarrollando herramientas en torno a la nueva API de Reporting (v1).

Con esto en mente:

• Si tu sitio ya usa la API de Reporting v0 con el encabezado Report-To, migra a la API de Reporting v1 (consulta los pasos para la migración). Si tu sitio ya usa la función de informes por incumplimientos de la Política de Seguridad del Contenido, consulta los pasos de migración específicos para los informes de CSP.
• Si tu sitio aún no usa la API de Reporting y ahora agregas la funcionalidad de informes, usa la nueva API de Reporting (v1) (el encabezado Reporting-Endpoints). Hay una excepción a esto: si necesitas usar el registro de errores de red, usa Report-To (v0). Actualmente, el registro de errores de red no es compatible con la versión 1 de la API de Reporting. Se desarrollará un nuevo mecanismo para el registro de errores de red.⏤Hasta que esté disponible, usa la versión 0 de la API de Reporting. Si necesitas el registro de errores de red junto con otros tipos de informes, usa Report-To (v0) y Reporting-Endpoints (v1). v0 te brinda el registro de errores de red y v1 te brinda informes de todos los demás tipos.

Pasos de la migración

Tu objetivo en esta migración es no perder los informes que solías obtener con v0.

Nota: Debido a que solo Chrome y Edge admiten la API de Reporting v0, no necesitas enfocarte en otros navegadores durante la migración a v1. Sin embargo, ten en cuenta que es posible que se agregue compatibilidad con más navegadores. Por el momento, no hay errores de seguimiento para estos navegadores, pero esto puede cambiar.

1. Paso 1 (hazlo ahora): Usa ambos encabezados: Report-To (v0) y Reporting-Endpoints (v1).

   Con esto, obtienes lo siguiente:

   • Informes de clientes de Chrome y Edge más recientes gracias a Reporting-Endpoints (v1).
   • Informes de clientes de Chrome y Edge más antiguos gracias a Report-To (v0).

   Las instancias de navegador que admitan Reporting-Endpoints usarán Reporting-Endpoints, y las que no, recurrirán a Report-To. El formato de solicitud y de informe es el mismo para v0 y v1.

2. Paso 2 (hazlo ahora): Asegúrate de que el encabezado Reporting-Endpoints esté configurado en todas las respuestas que podrían generar informes.

   Con la versión 0, puedes elegir configurar extremos de informes solo en algunas respuestas, y otros documentos (páginas) en ese origen usarían este extremo "ambiente". Con la v1, debido a la diferencia en el alcance, debes configurar el encabezado Reporting-Endpoints en todas las respuestas que puedan generar informes.

3. Paso 3 (comienza más adelante): Una vez que todos o la mayoría de los usuarios hayan actualizado a versiones posteriores de Chrome o Edge (96 y versiones posteriores), quita Report-To (v0) y conserva solo Reporting-Endpoints.

   Una excepción: Si necesitas informes de registro de errores de red, mantén Report-To hasta que se implemente un nuevo mecanismo para el registro de errores de red.

Consulta ejemplos de código en la guía de soluciones para la migración.

Pasos de migración para los informes de CSP

Existen dos formas de configurar los informes de incumplimiento de Content-Security-Policy:

• Solo con el encabezado de CSP a través de la directiva report-uri Tiene una amplia compatibilidad con navegadores, como Chrome, Firefox, Safari y Edge. Los informes se envían con el tipo de contenido application/csp-report y tienen un formato específico de CSP. Estos informes se denominan "Informes de nivel 2 del CSP" y no dependen de la API de informes.
• Con la API de Reporting, es a través del encabezado Report-To (heredado) o el más reciente Reporting-Endpoints (v1). Esta función solo es compatible con Chrome y Edge. Las solicitudes de informes tienen el mismo formato que otras solicitudes a la API de informes y el mismo tipo de contenido application/reports+json.

Ya no se recomienda usar el primer enfoque (solo report-uri) y el segundo tiene algunos beneficios. En particular, te permite usar una sola forma de configurar informes para todos los tipos de informes, así como establecer un extremo genérico (ya que todas las solicitudes de informes generadas a través de la API de informes⏤CSP y otros⏤tienen el mismo formato application/reports+json.

Sin embargo, solo algunos navegadores admiten report-to. Por lo tanto, se recomienda que mantengas report-uri junto con el enfoque de la API de informes (Report-To o, mejor, Reporting-Endpoints) para obtener informes de incumplimientos de CSP de varios navegadores. En un navegador que reconozca report-uri y report-to, se ignorará report-uri si report-to está presente. En un navegador que solo reconoce report-uri, solo se considerará report-uri.

1. Paso 1 (hazlo ahora): Si aún no lo hiciste, agrega report-to junto con report-uri. Los navegadores que solo admiten report-uri (Firefox) usarán report-uri, y los navegadores que también admiten report-to(Chrome y Edge) usarán report-to. Para especificar los extremos con nombre que usarás en report-to, usa los encabezados Report-To y Reporting-Endpoints. Esto garantiza que obtengas informes de clientes de Chrome y Edge más antiguos y más nuevos.

2. Paso 3 (comienza más tarde): Una vez que todos o la mayoría de los usuarios hayan actualizado a instalaciones posteriores de Chrome o Edge (96 y posteriores), quita Report-To (v0) y conserva solo Reporting-Endpoints. Mantén report-uri para seguir recibiendo informes de los navegadores que solo lo admiten.

Consulta los ejemplos de código para estos pasos en la migración de informes de CSP.

Migración: código de ejemplo

Descripción general

Si usas la API de informes heredada (v0) para obtener informes de incumplimientos de una COOP (encabezado Cross-Origin-Opener-Policy), una COEP (Cross-Origin-Embedder-Policy) o una política de documentos (encabezado Document-Policy), no es necesario que cambies estos encabezados de políticas cuando migres a la API de informes v1. Lo que sí necesitas es migrar del encabezado Report-To heredado al nuevo encabezado Reporting-Endpoints.

Si usas la API de informes heredada (v0) para obtener informes de incumplimientos de un CSP (encabezado Content-Security-Policy), es posible que debas modificar tu Content-Security-Policy como parte de la migración a la nueva API de informes (v1).

Migración básica

Código heredado (con v0)

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

Código nuevo (código de transición con v0 junto con v1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

Si ya tienes la función de informes en tu sitio, mantén Report-To solo de forma temporal (hasta que se actualicen la mayoría de los clientes de Chrome y Edge) para evitar perder informes.

Si necesitas el registro de errores de red, conserva Report-To hasta que el reemplazo de Network Error Logging esté disponible.

Código nuevo (solo con la v1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Así es como se verá tu código en el futuro, una vez que la mayoría de los clientes de Chrome y Edge se hayan actualizado y sean compatibles con la API v1.

Ten en cuenta que, con la versión 1, aún puedes enviar tipos de informes específicos a extremos específicos. Sin embargo, solo puedes tener una URL por extremo.

Observación de todas las páginas

Código heredado (con v0), por ejemplo, con Express

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

Con la versión 0, puedes configurar extremos de informes solo en algunas respuestas. Otros documentos (páginas) de ese origen usan automáticamente estos extremos ambientales. Aquí, los extremos configurados para "/" se usan para todas las respuestas, por ejemplo, para page1.

Código nuevo (con v1), por ejemplo, con Express

// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

Con la versión 1, debes configurar el encabezado Reporting-Endpoints en todas las respuestas que pueden generar informes.

Migración de informes del CSP

Código heredado, solo con URI de informe

Content-Security-Policy: ...; report-uri https://reports.example/main

Ya no se recomienda usar solo report-uri. Si tu código es similar al anterior, realiza la migración. Consulta los ejemplos de código nuevos a continuación (en verde).

Mejor código heredado, con report-uri y la directiva report-to con el encabezado Report-To (v0)

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

Esta es una mejor opción: este código usa report-to, el reemplazo más reciente de report-uri. Aún conserva report-uri para brindar retrocompatibilidad; varios navegadores no admiten report-to, pero sí admiten report-uri.

Aun así, esto podría ser mejor, ya que este código usa la API de informes v0 (encabezado Report-To). Migra a la versión 1: Consulta los ejemplos de "Código nuevo" a continuación (en verde).

Código nuevo, con report-uri y la directiva report-to con el encabezado Reporting-Endpoints (v1)

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

Mantén la directiva report-uri junto con la directiva report-to hasta que la directiva report-to sea compatible con todos los navegadores. Consulta la tabla de compatibilidad de navegadores.

Mantén Report-To junto a Reporting-Endpoints de forma temporal. Una vez que la mayoría de los visitantes de Chrome y Edge hayan actualizado a versiones del navegador posteriores a la 96, quita Report-To.

Lecturas adicionales

• Supervisa tu aplicación web con la API de Reporting (publicación principal sobre la API de Reporting)
• Especificación: API de informes heredada (versión 0)
• Especificación: nueva API de Reporting (v1)

Muchas gracias a Ian Clelland, Eiji Kitamura y Milica Mihajlija por sus comentarios y sugerencias sobre este artículo.