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

Diferencias entre la v0 y la v1

Qué cambiará

  • La superficie 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 (nuevo)
 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 nombres extremos. Al igual que en la versión 0, 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) relacionados el origen usaría automáticamente estos extremos de ambiente.

v1 (nuevo)

En la versión 1, debes configurar el encabezado Reporting-Endpoints en todas las respuestas que podrían generar informes.

  • 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

API de Reporting heredada (v0)
Encabezado Report-To
Nueva API de Reporting (v1)
Encabezado Reporting-Endpoints
Navegadores compatibles Chrome 69 o versiones posteriores, y Edge 69 o versiones posteriores. Chrome 96 o versiones posteriores, y Edge 96 y versiones posteriores. Firefox es compatible. Safari no tiene objeciones. Consulta los indicadores del navegador.
Extremos Envía informes a cualquiera de los múltiples recopiladores de informes (múltiples 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
  • Choque
  • COOP/COEP
  • Nivel 3 de la Política de Seguridad del Contenido (CSP nivel 3)
  • Registro de errores de red (NEL)
Obtén más información sobre los tipos de informes en la publicación API de Reporting.
Sin cambios, excepto en Network Error Logging (NEL): Esto 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 (agrupación en lotes) Los diferentes documentos (páginas) o sitios/orígenes que generan un informe aproximadamente en la misma época y que tienen el mismo extremo de informes se agruparán en lotes: se enviarán en el mismo mensaje al extremo de los 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, no se agruparán en lotes. Este es un mecanismo para mitigar los ataques de privacidad.
  • Los informes de un mismo documento (página) pueden enviarse juntos.
Compatibilidad con el balanceo de cargas y las prioridades No

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

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 junto con 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 cuenta con la función de informes en su sitio, conserve Report-To solo de manera temporal (hasta que se hayan actualizado la mayoría de los clientes de Chrome y Edge) para no perder los informes.

Si necesitas el registro de errores de red, conserva Report-To hasta que se reemplace el registro de errores de red pase a estar disponible.

Código nuevo (solo con 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 la mayoría de los clientes de Chrome y Edge se hayan actualizado y sean compatibles con la API v1.

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

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. Otra opción los documentos (páginas) de ese origen usan automáticamente estos extremos de ambiente. Aquí, los extremos establecen de "/" 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(...)
});

En la versión 1, debes configurar el encabezado Reporting-Endpoints en todos las respuestas que podrían generar informes.

Migración de informes de CSP

Código heredado, solo con URI de informe
Content-Security-Policy: ...; report-uri https://reports.example/main

El uso exclusivo de report-uri ya no es necesario. recomendado. Si tu código es similar al anterior, realiza la migración. Consulta los siguientes ejemplos de código nuevo (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. Aún conserva report-uri para brindar retrocompatibilidad. varios los navegadores no son compatibles report-to pero admiten report-uri

Aun así, esto podría ser mejor, ya que este código usa la API de informes v0 (encabezado Report-To). Migra a la versión 1: consulta la Código nuevo ejemplos 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 la directiva report-to. es compatible con todos los navegadores. Consulta la página sobre compatibilidad de navegadores de la tabla.

Mantén Report-To junto a Reporting-Endpoints temporalmente. Una vez que la mayoría de las apps de Chrome los visitantes actualizaron el navegador a más de 96 versiones, por lo que debes quitar Report-To.

Lecturas adicionales

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