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.
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
{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.
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.
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.
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
deContent-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 |
|
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. |
|
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 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, usaReport-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 tantoReport-To
(v0) comoReporting-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.
Paso 1 (hazlo ahora): Usa ambos encabezados:
Report-To
(v0) yReporting-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ánReporting-Endpoints
. que no lo hagan recurrirán aReport-To
. El formato de la solicitud y el informe es el mismo para v0 y v1.- Informes de clientes más recientes de Chrome y Edge gracias a
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.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 soloReporting-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 contenidoapplication/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 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 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
.
Paso 1 (hacerlo ahora): Si aún no lo has agregado, agrega
report-to
junto conreport-uri
. Los navegadores que solo admitenreport-uri
(Firefox) usaránreport-uri
, y los navegadores que también lo hagan la compatibilidadreport-to
(Chrome, Edge) usaráreport-to
. Para especificar los extremos con nombre que usarás Enreport-to
, usa los encabezadosReport-To
yReporting-Endpoints
. Esto garantiza que obtengas informes de clientes de Chrome y Edge más antiguos y más nuevos.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 soloReporting-Endpoints
. Conservarreport-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" }] }
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.
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
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
.
// 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
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).
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).
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
- 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 .