Hay una nueva versión disponible de la API de Reporting. Es más privada y es más probable que se admita en todos los navegadores.
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 una nueva versión de la API de Reporting disponible. La nueva API es más eficaz y es más probable que sea compatible con todos los navegadores.
Resumen
Desarrolladores de sitios
Si ya tienes la funcionalidad de informes para tu sitio, migra a la versión 1 con el encabezado nuevo
(Reporting-Endpoints
), pero conserva el encabezado heredado durante un tiempo (Report-To
).
Consulta Migración: código de ejemplo.
Si recién estás agregando la funcionalidad 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 operas uno propio, se 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 ejemplos 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)
- Code para el sitio de demostración
Diferencias entre la versión 0 y la versión 1
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.
Con la versión 0, puedes establecer extremos de informes solo en algunas respuestas. Otros documentos (páginas) de ese origen usarían automáticamente estos extremos de ambiente.
Con la versión 1, debes establecer el encabezado Reporting-Endpoints
en todas las respuestas que puedan generar informes.
- Ambas APIs admiten los mismos tipos de informes, con una excepción: la versión 1 no es compatible con los informes de errores de red. Obtén más información en los pasos de migración.
- La versión 0 no es compatible con todos los navegadores, y tampoco será compatible con esta versión, pero es más probable que la versión v0 sea compatible con varios navegadores en el futuro.
Lo que no se modifica
- El formato y la estructura de los informes no se modifican.
- La solicitud que envía el navegador al extremo sigue siendo una solicitud
POST
deContent-type
application/reports+json
. - La asignación de ciertos extremos a ciertos tipos de informes se admite en la v0 y la v1.
- La función del extremo
default
no se modifica. La API de Reporting v1 no tiene impacto en
ReportingObserver
.ReportingObserver
continúa obteniendo acceso a todos los informes observables, y su formato es idéntico.
Todas las diferencias entre la versión 0 y la versión 1
API de informes heredados (v0) Encabezado Report-To |
Nueva API de Reporting (v1) Encabezado Reporting-Endpoints |
|
---|---|---|
Navegadores compatibles | Chrome 69 y versiones posteriores, y Edge 69 y versiones posteriores. | Chrome 96 (o versiones posteriores) y Edge 96 (o versiones posteriores). Firefox es compatible. Safari no tiene objeciones. Consulta los indicadores del navegador. |
Extremos | Envía informes a cualquiera de varios recopiladores de informes (varias 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 |
|
Sin cambios, excepto por Network Error Logging (NEL): 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 (lotes) | Los diferentes documentos (páginas) o sitios/orígenes que generen un informe aproximadamente al mismo tiempo y que tengan el mismo extremo de informes se agruparán en lotes: se enviarán en el mismo mensaje al extremo de informes. |
|
Compatibilidad con el balanceo de cargas y las prioridades | Sí | No |
Desarrolladores de extremos: Esperan más tráfico
Si configuraste tu propio servidor como extremo de informes o si estás desarrollando o manteniendo un recopilador de informes como servicio, es posible que recibas más tráfico hacia ese extremo.
Esto se debe a que los informes no se agrupan en lotes con la versión 1 de la API de Reporting, como sucede con la versión 0 de la API de Reporting. 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 del extremo aumentará.
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 espera compatibilidad entre navegadores para la v1 (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).
Teniendo esto en cuenta:
- Si tu sitio ya usa la versión 0 de la API de Reporting con el encabezado
Report-To
, migra a la versión 1 de la API de Reporting (consulta los pasos de migración). Si tu sitio ya usa la función de informes sobre 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 todavía no usa la API de Reporting y ahora agregas 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, usaReport-To
(v0). Por el momento, la versión 1 de la API de Reporting no admite el registro de errores de red. 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 a otros tipos de informes, usa ambas:Report-To
(v0) yReporting-Endpoints
(v1). La v0 te brinda informes de errores de red y v1 te brinda informes de todos los otros tipos.
Pasos de la migración
Tu objetivo en esta migración es no perder los informes que solías obtener con la versión 0.
Paso 1 (hacerlo ahora): Usa ambos encabezados:
Report-To
(v0) yReporting-Endpoints
(v1).Con él obtienes lo siguiente:
- Informes de los clientes más recientes de Chrome y Edge gracias a
Reporting-Endpoints
(v1). - Informes de clientes antiguos de Chrome y Edge gracias a
Report-To
(v0).
Las instancias de navegador que admiten
Reporting-Endpoints
usaránReporting-Endpoints
, y las que no lo hagan, recurrirán aReport-To
. El formato de solicitud y de informe es el mismo para las versiones 0 y 1.- Informes de los clientes más recientes de Chrome y Edge gracias a
Paso 2 (hazlo ahora): Asegúrate de que el encabezado
Reporting-Endpoints
esté configurado en todas las respuestas que podrían generar informes.Con la versión 0, podrías optar por establecer 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 los alcances, debes establecer el encabezado
Reporting-Endpoints
en todas las respuestas que podrían generar informes.Paso 3 (comienza más tarde): Una vez que todos o la mayoría de los usuarios actualicen a las instalaciones posteriores de Chrome o Edge (96 y versiones posteriores), quita
Report-To
(v0) y conserva soloReporting-Endpoints
.Una excepción: si necesitas informes de Network Error Logging, mantén
Report-To
hasta que se implemente un nuevo mecanismo para el registro de errores de red.
Consulta ejemplos de código en la guía de soluciones de migración.
Pasos de migración para los informes de CSP
Existen dos formas de configurar los informes de incumplimientos de la Política de Seguridad del Contenido:
- Solo con el encabezado de la CSP mediante la directiva
report-uri
Tiene una amplia compatibilidad con navegadores Chrome, Firefox, Safari y Edge. Los informes se envían con el tipo de contenidoapplication/csp-report
y tienen un formato específico para CSP. Estos informes se denominan "informes de CSP nivel 2" y no se basan en la API de informes. - Con la API de Reporting, es mediante el encabezado
Report-To
(heredado) o elReporting-Endpoints
más reciente (v1). Esta opción solo se admite en Chrome y Edge. Las solicitudes de informes tienen el mismo formato que otras solicitudes a la API de Reporting y el mismo tipo de contenidoapplication/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 que se generan con la API de informes ⏤CSP y otras ⏤ 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 Reporting (Report-To
o mejor, Reporting-Endpoints
) para obtener informes de incumplimiento de la CSP de varios navegadores. En un navegador que reconozca report-uri
y report-to
, se ignorará report-uri
si report-to
está presente. En un navegador que reconozca solo a report-uri
, solo se considerará a report-uri
.
Paso 1 (hazlo ahora): Si todavía no lo agregaste, agrega
report-to
junto conreport-uri
. Los navegadores que solo admitenreport-uri
(Firefox) usaránreport-uri
, y los navegadores que también son compatibles conreport-to
(Chrome, Edge) usaránreport-to
. Para especificar los extremos con nombre que usarás enreport-to
, usa los encabezadosReport-To
yReporting-Endpoints
. Esto garantiza que obtengas informes de los clientes de Chrome y Edge más antiguos y más recientes.Paso 3 (comienza más tarde): Una vez que todos o la mayoría de los usuarios actualicen a las instalaciones posteriores de Chrome o Edge (96 y versiones posteriores), quita
Report-To
(v0) y conserva soloReporting-Endpoints
. Manténreport-uri
para seguir recibiendo informes de los navegadores que solo lo admiten.
Consulta ejemplos de código de 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 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ítica mientras migras a la API de Reporting v1. Lo que debes hacer es migrar del encabezado Report-To
heredado al encabezado Reporting-Endpoints
nuevo.
Si usas la API de Reporting heredada (v0) para obtener informes de incumplimientos de un CSP (encabezado Content-Security-Policy
), es posible que debas modificar el 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 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.
Observando 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 (entrada principal sobre la API de Reporting)
- Especificación: API de informes heredados (v0)
- Especificación: nueva API de Reporting (v1)
Hero image de Nine Koepfer / @enka80 en Unsplash, editada. Agradecemos a Ian Clelland, Eiji Kitamura y Milica Mihajlija por sus opiniones y sugerencias en este artículo.