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 ocurren en tu sitio a medida que los visitantes lo usan. Te brinda visibilidad sobre las intervenciones y 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 simple 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 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 extremo o ejecutas el tuyo propio, 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 un ejemplo de código.

Registro de errores de red

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)
• 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 versión 1 no admite los informes de errores de red. Obtén más información en los pasos de migración.
• La versión v0 no se admite ni se admitirá en todos los navegadores. Es más probable que la versión v1 se admita en varios navegadores en el futuro.

Qué se mantiene igual

• No se modificaron el formato ni la estructura de los informes.
• 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 las versiones v0 y v1.
• El rol del extremo default no cambia.

• La versión 1 de la API de Reporting no tiene 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: Esperen más tráfico

Si configuraste tu propio servidor como extremo de informes, o si desarrollas o mantienes un recopilador de informes como servicio, espera más tráfico en 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 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 entre navegadores para la versión 1 (a diferencia de la versión 0, 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, haz 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 función de informes para los incumplimientos de la Política de Seguridad del Contenido, consulta los pasos específicos para la migración de 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 esta regla: Si necesitas usar Network Error Logging, usa Report-To (v0). Actualmente, Network Error Logging no se admite en la API de Reporting v1. Se desarrollará un nuevo mecanismo para Network Error Logging. Hasta que esté disponible, usa la versión 0 de la API de Reporting. Si necesitas Network Error Logging junto con otros tipos de informes, usa ambos Report-To (v0) y Reporting-Endpoints (v1). La versión v0 te proporciona Network Error Logging y la versión v1 te proporciona 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 versión 0.

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

   Con esta opción, obtendrás lo siguiente:

   • Informes de clientes más recientes de Chrome y Edge gracias a Reporting-Endpoints (v1).
   • Informes de clientes anteriores 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 admitan recurrirán a Report-To. El formato de la solicitud y del informe es el mismo para las versiones 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, podías elegir configurar 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 el alcance, debes establecer 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 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 Network Error Logging, mantén Report-To hasta que se implemente un nuevo mecanismo para Network Error Logging.

Consulta ejemplos de código en el recetario de migración.

Pasos para la migración de 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 Tiene una amplia compatibilidad con los 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 el CSP. Estos informes se denominan "Informes de CSP de nivel 2" y no dependen de la API de Reporting.
• Con la API de Reporting, esto se realiza 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 de la API de Informes y el mismo tipo de contenido application/reports+json.

El primer enfoque (solo report-uri) ya no se recomienda, y el segundo 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 otros⏤tienen el mismo formato application/reports+json.

Sin embargo, solo unos pocos 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 aún, Reporting-Endpoints) para obtener informes de incumplimiento de la CSP de varios navegadores. En un navegador que reconoce report-uri y report-to, se ignorará report-uri si está presente report-to. 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 recibas informes de los 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 tus usuarios hayan actualizado a versiones 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 admiten este formato.

Consulta ejemplos de código para estos pasos en Migración de informes de CSP.

Migración: código de ejemplo

Descripción general

Si utilizas la API de Reporting heredada (v0) para obtener informes de incumplimientos de una política de COOP (encabezado Cross-Origin-Opener-Policy), una política de 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 Reporting v1. Lo que sí debes hacer 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 ajustar 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.

Observa 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: Nueva API de Reporting (v1)

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