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

La API de Reporting te informa sobre los errores que se producen en tu sitio cuando los visitantes lo usan. Le da tu visibilidad de las intervenciones del navegador, las fallas del navegador, los incumplimientos de la política de seguridad del contenido, Incumplimientos de COOP/COEP, advertencias de baja y mucho más

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

Resumen

Desarrolladores de sitios

Si ya cuenta con la función de informes en su sitio, migre a la versión 1 con el nuevo encabezado. (Reporting-Endpoints), pero se mantendrá el encabezado heredado durante un tiempo (Report-To). Consulta Migración: código de ejemplo.

Si agrega la función de informes a su sitio recientemente: Use 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 operas un servicio de extremo o uno propio, espera más tráfico a medida que o desarrolladores externos migran a la API de Reporting v1 (encabezado Reporting-Endpoints).

Sigue leyendo para conocer los detalles y el 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, cambie de la API de Reporting v0 a ese mecanismo nuevo.

Demostración y código

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

Diferencias entre la v0 y la 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 API admiten los mismos tipos de informes, con una excepción: la versión 1 no admite informes de errores de red. Obtén más información en los pasos para la migración.
• v0 no es compatible con todos los navegadores ni lo será. es más probable que se admita la versión 1 varios navegadores en el futuro.

Qué se mantiene sin cambios

• El formato y la estructura de los informes no se modifican.
• 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.
• La función del extremo default no se modificó.

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

Todas las diferencias entre v0 y v1

Desarrolladores de extremos: Esperan más tráfico

Si configuraste tu propio servidor como un extremo de informes o si estás desarrollando o manteniendo un de registro como servicio, se espera más tráfico hacia ese extremo.

Esto se debe a que los informes no se agrupan en lotes con la API de Reporting v1 como con la API de Reporting v0. Por lo tanto, Cuando los desarrolladores de aplicaciones comiencen a migrar a la API de Reporting v1, la cantidad de informes será seguirán siendo similares, pero el volumen de solicitudes al servidor de extremo aumentará.

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

¿Qué deberías hacer?

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

• Las señales del navegador son positivas, lo que significa que es posible que haya compatibilidad entre navegadores para la versión 1 (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).

Con esto en mente:

• Si tu sitio ya usa la API de Reporting v0 con el encabezado Report-To, migra a la Versión 1 de la API de Reporting (consulta los pasos para la migración). Si tu sitio ya usa funcionalidades para denunciar 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, sigue estos pasos: usar 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). Registro de errores de red actualmente, no es compatible con la versión 1 de la API de Reporting. Un nuevo mecanismo para el registro de errores de red desarrollarse⏤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). v0 le proporciona el registro de errores de red y la versión 1 le 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.

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

   De este modo, obtienes 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 compatibles con Reporting-Endpoints usarán Reporting-Endpoints. que no lo hagan recurrirán a Report-To. El formato de la solicitud y el informe es el mismo para v0 y v1.

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

   Con la versión 0, puedes establecer extremos de informes solo en algunas respuestas y en otros documentos (páginas) de ese origen usarían esta opción extremo. Con la versión 1, debido a la diferencia en 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 hayan actualizado sus cuentas a Chrome o Edge más adelante instalaciones (96 y 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 se cree una nueva. de red 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

Content-Security-Policy tiene dos métodos los informes de incumplimiento se pueden configurar:

• Solo con el encabezado de la CSP a través de la directiva report-uri Esto brinda 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 nivel 2 de CSP”. y hacer no dependan de la API de Reporting.
• Con la API de Reporting, esto se logra a través del encabezado Report-To (heredado) o la versión más reciente. Reporting-Endpoints (v1) Esta opción solo se admite en Chrome y Edge. Las solicitudes de informes tienen el elemento 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 generadas mediante la API de Reporting ⏤CSP y otras⏤tienen el mismo formato application/reports+json).

Sin embargo, solo algunos navegadores admiten report-to. Por lo tanto, te recomendamos 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 desde varios navegadores. En una 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 (hacerlo ahora): Si aún no lo has agregado, 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 lo hagan la compatibilidad report-to(Chrome, Edge) usará 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 sus cuentas a Chrome o Edge más adelante instalaciones (96 y posteriores), quita Report-To (v0) y conserva solo Reporting-Endpoints. Conservar report-uri para que sigas recibiendo informes para los navegadores que solo lo admiten.

Consulta ejemplos de código para 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 incumplimiento de una COOP (encabezado Cross-Origin-Opener-Policy), un COEP (Cross-Origin-Embedder-Policy) o una política de documentos (Document-Policy encabezado): No es necesario que cambies estos encabezados de política durante la migración a la versión 1 de la API de Reporting. Lo que debes hacer 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 (Content-Security-Policy), es posible que debas ajustar tu Content-Security-Policy como parte de tu 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 versión 1, aún puedes enviar tipos de informes específicos a extremos específicos. Pero tú solo puede 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: nueva API de Reporting (v1)

Hero image de Nine Koepfer / @enka80 en Unsplash, editado. Agradecimientos a Ian Clelland, Eiji Kitamura y Milica Mihajlija por sus opiniones y sugerencias .