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 se admita en 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, consulta 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 eficaz y es más probable que sea compatible con todos los navegadores.

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

Resumen

Desarrolladores de sitios

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

Si recién estás agregando la funcionalidad de informes a tu sitio: usa solo el encabezado nuevo (Reporting-Endpoints).

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

Desarrolladores de servicios de informes

Si mantienes un servicio de extremos o operas uno propio, se espera más tráfico a medida que tú o los desarrolladores externos migren a la API de Reporting v1 (encabezado Reporting-Endpoints).

Sigue leyendo para obtener detalles y ejemplos de código.

Registro de errores de red

Precaución: Si usas el Registro de errores de red, sigue usando Report-To (v0) porque no es compatible con la API de Reporting v1.

Se desarrollará un nuevo mecanismo para el registro de errores de red. Cuando 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)
• Code para el sitio de demostración

Diferencias entre la versión 0 y la versión 1

Qué cambiará

• La plataforma de la API es diferente.

v0 (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 con nombre y la directiva report-to en otros encabezados para hacer referencia a estos grupos de extremos.

v1 (nueva)

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

v1 usa el encabezado Reporting-Endpoints para configurar extremos con nombre. Al igual que v0, usa la directiva report-to en otros encabezados para hacer referencia a estos grupos de extremos.

• El alcance del informe es diferente.

v0 (heredada)

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

v1 (nueva)

Con la versión 1, debes establecer 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 versión 1 no es compatible con los informes de errores de red. Obtén más información en los pasos de migración.
• La versión 0 no es compatible con todos los navegadores, y tampoco será compatible con esta versión, pero es más probable que la versión v0 sea compatible con varios navegadores en el futuro.

Lo que no se modifica

• El formato y la estructura de los informes no se modifican.
• La solicitud que envía el navegador al extremo sigue siendo una solicitud POST de Content-type application/reports+json.
• La asignación de ciertos extremos a ciertos tipos de informes se admite en la v0 y la v1.
• La función del extremo default no se modifica.

• La API de Reporting v1 no tiene impacto en ReportingObserver. ReportingObserver continúa obteniendo acceso a todos los informes observables, y su formato es idéntico.

Todas las diferencias entre la versión 0 y la versión 1

	API de informes heredados (v0) Encabezado Report-To	Nueva API de Reporting (v1) Encabezado Reporting-Endpoints
Navegadores compatibles	Chrome 69 y versiones posteriores, y Edge 69 y versiones posteriores.	Chrome 96 (o versiones posteriores) y Edge 96 (o versiones posteriores). Firefox es compatible. Safari no tiene objeciones. Consulta los indicadores del navegador.
Extremos	Envía informes a cualquiera de varios recopiladores de informes (varias URLs definidas por grupo de extremos).	Envía informes a recopiladores de informes específicos (solo una URL definida por extremo).
Superficie de la API	Usa el encabezado `Report-To` para configurar grupos de extremos con nombre.	Usa el encabezado `Reporting-Endpoints` para configurar extremos con nombre.
Tipos de informes que se pueden generar con esta API	Baja Intervención Accidente automovilístico COOP/COEP Política de Seguridad del Contenido 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 de la API de Reporting.	Sin cambios, excepto por Network Error Logging (NEL): 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 (lotes)	Los diferentes documentos (páginas) o sitios/orígenes 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 documentos (páginas) diferentes nunca se envían juntos. Incluso si dos documentos (páginas) del mismo origen generan un informe al mismo tiempo, para el mismo extremo, estos no se agruparán en lotes. 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 y las prioridades	Sí	No

Desarrolladores de extremos: Esperan más tráfico

Si configuraste tu propio servidor como extremo de informes o si estás desarrollando o manteniendo un recopilador de informes como servicio, es posible que recibas más tráfico hacia ese extremo.

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

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 espera compatibilidad entre navegadores para la v1 (a diferencia de la v0, que solo es compatible con Chrome y Edge).
• La API es más eficiente.
• Se están desarrollando herramientas en torno a la nueva API de Reporting (v1).

Teniendo esto en cuenta:

• Si tu sitio ya usa la versión 0 de la API de Reporting con el encabezado Report-To, migra a la versión 1 de la API de Reporting (consulta los pasos de migración). Si tu sitio ya usa la función de informes sobre 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 todavía no usa la API de Reporting y ahora agregas 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). Por el momento, la versión 1 de la API de Reporting no admite el registro de errores de red. Se desarrollará un nuevo mecanismo para el registro de errores de red ⏤hasta que esté disponible, usa la API de Reporting v0. Si necesitas el registro de errores de red junto a otros tipos de informes, usa ambas: Report-To (v0) y Reporting-Endpoints (v1). La v0 te brinda informes de errores de red y v1 te brinda informes de todos los otros tipos.

Pasos de la migración

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

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 la v1. Sin embargo, ten en cuenta que es posible que próximamente se admita más con los navegadores. Por el momento, no hay errores de seguimiento para estos navegadores, pero esto puede cambiar.

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

   Con él obtienes lo siguiente:

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

   Las instancias de navegador que admiten Reporting-Endpoints usarán Reporting-Endpoints, y las que no lo hagan, recurrirán a Report-To. El formato de solicitud y de informe es el mismo para las versiones 0 y 1.

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, podrías optar por establecer extremos de informes solo en algunas respuestas, y otros documentos (páginas) en ese origen usarían este extremo "ambiente". Con la versión 1, debido a la diferencia en los alcances, debes establecer el encabezado Reporting-Endpoints en todas las respuestas que podrían generar informes.

3. Paso 3 (comienza más tarde): Una vez que todos o la mayoría de los usuarios actualicen a las instalaciones 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 Network Error Logging, 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 de migración.

Pasos de migración para los informes de CSP

Existen dos formas de configurar los informes de incumplimientos de la Política de Seguridad del Contenido:

• Solo con el encabezado de la CSP mediante la directiva report-uri Tiene una amplia compatibilidad con navegadores Chrome, Firefox, Safari y Edge. Los informes se envían con el tipo de contenido application/csp-report y tienen un formato específico para CSP. Estos informes se denominan "informes de CSP nivel 2" y no se basan en la API de informes.
• Con la API de Reporting, es mediante el encabezado Report-To (heredado) o el Reporting-Endpoints más reciente (v1). Esta opción solo se admite en Chrome y Edge. Las solicitudes de informes tienen el mismo formato que otras solicitudes a la API de Reporting 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 (porque todas las solicitudes de informes que se generan con la API de informes ⏤CSP y otras ⏤ 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 Reporting (Report-To o mejor, Reporting-Endpoints) para obtener informes de incumplimiento de la 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 reconozca solo a report-uri, solo se considerará a report-uri.

1. Paso 1 (hazlo ahora): Si todavía no lo agregaste, 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 son compatibles con report-to(Chrome, 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 los clientes de Chrome y Edge más antiguos y más recientes.

2. Paso 3 (comienza más tarde): Una vez que todos o la mayoría de los usuarios actualicen a las instalaciones posteriores de Chrome o Edge (96 y versiones 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 ejemplos de código de estos pasos en la migración de informes de la CSP.

Migración: código de ejemplo

Descripción general

Si usas la API de Reporting 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ítica mientras migras a la API de Reporting v1. Lo que debes hacer es migrar del encabezado Report-To heredado al encabezado Reporting-Endpoints nuevo.

Si usas la API de Reporting heredada (v0) para obtener informes de incumplimientos de un CSP (encabezado Content-Security-Policy), es posible que debas modificar el Content-Security-Policy como parte de la migración a la nueva API de Reporting (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 y 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 funcionalidad de informes en tu sitio, conserva Report-To solo temporalmente (hasta que se hayan actualizado 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 Error de red 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 se actualice la mayoría de los clientes de Chrome y Edge y sean compatibles con la versión 1 de la API.

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.

Observando 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 establecer extremos de informes solo en algunas respuestas. Otros documentos (páginas) en ese origen usan automáticamente estos extremos de ambiente. Aquí, los extremos establecidos para "/" se usan en 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 podrían generar informes.

Migración de informes de CSP

Código heredado, solo con report-uri

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

Ya no se recomienda usar solo report-uri. Si el código es similar al anterior, realiza la migración. Consulta los ejemplos de código nuevo 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"

Esto es mejor: este código usa report-to, el reemplazo más reciente de report-uri. Sigue usando report-uri para garantizar la retrocompatibilidad. Varios navegadores no admiten report-to, pero sí report-uri.

De todos modos, esto podría mejorar: este código usa la versión 0 de la API de Reporting (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 del navegador.

Mantén Report-To junto a Reporting-Endpoints temporalmente. Una vez que la mayoría de los visitantes de Chrome y Edge se hayan actualizado a las más de 96 versiones del navegador, quita Report-To.

Lecturas adicionales

• Supervisa tu aplicación web con la API de Reporting (entrada principal sobre la API de Reporting)
• Especificación: API de informes heredados (v0)
• Especificación: nueva API de Reporting (v1)

Hero image de Nine Koepfer / @enka80 en Unsplash, editada. Agradecemos a Ian Clelland, Eiji Kitamura y Milica Mihajlija por sus opiniones y sugerencias en este artículo.