Migra a la API de Reporting v1

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

Maud Nalpas

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 disponible una nueva versión de la API de Reporting. La nueva API es más liviana y es más probable que sea compatible con todos los navegadores.

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 ahora mismo, 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 administras un servicio de extremo o tienes el tuyo propio, espera más tráfico a medida que tú o los desarrolladores externos migren a la versión 1 de la API de Reporting (encabezado Reporting-Endpoints).

Sigue leyendo para obtener detalles y un código de ejemplo.

Registro de errores de red

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.

 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

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

• El alcance del informe es diferente.

• 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 de la migración.
• La versión 0 no es compatible con todos los navegadores y no lo será en el futuro. Es más probable que la versión 1 sea compatible con varios navegadores en el futuro.

Qué permanece sin cambios

• El formato y la estructura de los informes no cambian.
• 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 es compatible con la v0 y la v1.
• El rol del extremo default no cambia.

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

Todas las diferencias entre v0 y v1

Desarrolladores de extremos: Se espera más tráfico

Si configuraste tu propio servidor como un extremo de informes o si estás desarrollando o manteniendo un recopilador de informes como servicio, espera más tráfico en 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?

El uso de 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, ten en cuenta lo siguiente:

• 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 de migración). Si tu sitio ya usa la funcionalidad de informes para los incumplimientos de la Política de Seguridad del Contenido, consulta los pasos específicos de migración 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 ambos: 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 la v0.

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 puedan 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 el libro de recetas de 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 para 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 enfoque 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 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 reconoce 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 que también admiten 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 clientes de Chrome y Edge más antiguos y más nuevos.

2. 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. 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

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

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

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

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

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

// 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(...)
});

Migración de informes del CSP

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

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

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
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.