Migra a la API de Reporting v1

Hay 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 ocurren en tu sitio cuando los visitantes lo usan. Te brinda visibilidad sobre las intervenciones del navegador, los bloqueos 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. La nueva API es más simple y es más probable que sea compatible con todos los navegadores.

Resumen

Desarrolladores de sitios

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

Si recién ahora agregas la función 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 usas el tuyo, 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 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 API de Reporting v0 a ese nuevo mecanismo.

Demostración y código

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

Diferencias entre v0 y v1

Qué cambiará

• La superficie 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 informes de errores de red. Obtén más información en los pasos de migración.
• La v0 no es compatible con todos los navegadores y no lo será. Es más probable que la v1 sea compatible con varios navegadores en el futuro.

Qué no cambiará

• 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 se admite en la v0 y la v1.
• El rol del extremo default no cambia.

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

Todas las diferencias entre v0 y v1

Desarrolladores de extremos: Esperen 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 a ese extremo.

Esto se debe a que los informes no se procesan por lotes con la API de Reporting v1 como lo hacen con la API de Reporting v0. 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 de extremos aumentará.

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

Teniendo esto en cuenta:

• Si tu sitio ya usa la API de Reporting v0 con el Report-To encabezado, migra a la API de Reporting v1 (consulta los pasos de migración). Si tu sitio ya usa la función de informes para los 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 función 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 API de Reporting v1. 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 con otros tipos de informes, usa tanto Report-To (v0) como Reporting-Endpoints (v1). La v0 te brinda el registro de errores de red y la v1 te brinda informes de todos los demás tipos.

Pasos de la migración

El objetivo de 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, obtendrás lo siguiente:

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

   Las instancias del navegador que admiten Reporting-Endpoints usarán Reporting-Endpoints, y las instancias que no lo hagan volverán a Report-To. El formato de solicitud y de informe es el mismo para la v0 y la 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 v0, podías elegir configurar extremos de informes solo en algunas respuestas, y otros documentos (páginas) de ese origen usarían este extremo "ambiental". 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 tarde): Una vez que todos o la mayoría de tus usuarios se hayan actualizado a 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 registro de errores de red, conserva Report-To hasta que esté disponible 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 la Política de Seguridad del Contenido:

• Solo con el encabezado de CSP a través de la directiva report-uri. Esto tiene una amplia compatibilidad con navegadores, en 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 de nivel 2" y no dependen de la API de Reporting.
• Con la API de Reporting, es decir, a través del encabezado Report-To (heredado) o el Reporting-Endpoints más reciente (v1). Esto solo es compatible con Chrome y Edge. Las solicitudes de informes tienen el mismo formato que otras solicitudes de 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 usar el segundo enfoque tiene algunos beneficios. En particular, te permite usar una sola forma de configurar los 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 Reporting, CSP y otras, tienen el mismo formato application/reports+json.

Sin embargo, solo unos pocos navegadores admiten report-to. Por lo tanto, te recomendamos que conserves report-uri junto con el enfoque de la API de Reporting (Report-To o mejor, Reporting-Endpoints) para obtener informes de incumplimiento 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 tendrá en cuenta report-uri.

1. Paso 1 (hazlo ahora): Si aún 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 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 más antiguos y más recientes de Chrome y Edge.

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

Consulta 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 Reporting heredada (v0) para obtener informes de incumplimiento de un COOP (encabezado Cross-Origin-Opener-Policy), un COEP (Cross-Origin-Embedder-Policy) o una política de documentos (encabezado Document-Policy), no necesitas cambiar estos encabezados de política mientras migras a la API de Reporting v1. Lo que sí necesitas es migrar del encabezado Report-To heredado al nuevo encabezado Reporting-Endpoints.

Si usas la API de Reporting heredada (v0) para obtener informes de incumplimiento de un CSP (encabezado Content-Security-Policy), es posible que debas ajustar tu Content-Security-Policy como parte de la migración a la nueva API de Reporting (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 v1, 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 de 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 Reporting heredada (v0)
• Especificación: API de Reporting nueva (v1)

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