Une nouvelle version de l'API Reporting est disponible. Il est plus privé et plus susceptible d'être compatible avec les navigateurs.
L'API Reports vous informe des erreurs qui se produisent sur votre site lorsque les visiteurs l'utilisent. Il vous permet de voir les interventions du navigateur, les plantages du navigateur, les cas de non-respect de Content-Security-Policy, les cas de non-respect de COOP/COEP, les avertissements d'abandon, etc.
Une nouvelle version de l'API Reporting est disponible. La nouvelle API est plus simple et plus susceptible d'être compatible avec les navigateurs.
Résumé
Développeurs de sites
Si vous disposez déjà d'une fonctionnalité de création de rapports pour votre site: migrez vers la version 1 à l'aide du nouvel en-tête (Reporting-Endpoints
), mais conservez l'ancien en-tête pendant un certain temps (Report-To
). Consultez Migration: exemple de code.
Si vous ajoutez actuellement une fonctionnalité de création de rapports à votre site: utilisez uniquement le nouvel en-tête (Reporting-Endpoints
).
⚠️ Dans les deux cas, veillez à définir l'en-tête Reporting-Endpoints
sur toutes les réponses susceptibles de générer des rapports.
Développeurs de services de reporting
Si vous gérez un service de point de terminaison ou que vous en exploitez un, attendez-vous à plus de trafic lorsque vous ou des développeurs externes migrerez vers la version 1 de l'API Reporting (en-tête Reporting-Endpoints
).
Lisez la suite pour en savoir plus et obtenir un exemple de code.
Journalisation des erreurs réseau
Un nouveau mécanisme de journalisation des erreurs réseau sera développé. Une fois qu'il sera disponible, passez de la version 0 de l'API Reporting à ce nouveau mécanisme.
Démonstration et code
- Site de démonstration: nouvelle API Reporting (v1)
- Code pour le site de démonstration
Différences entre les versions v0 et v1
Ce qui change
- La surface de l'API est différente.
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
- La portée du rapport est différente.
Avec la version 0, vous ne pouvez définir des points de terminaison de création de rapports que sur certaines réponses. Les autres documents (pages) de cette origine utiliseraient automatiquement ces points de terminaison ambiants.
Avec la version 1, vous devez définir l'en-tête Reporting-Endpoints
sur toutes les réponses susceptibles de générer des rapports.
- Les deux API sont compatibles avec les mêmes types de rapports, à une exception près: la version 1 n'est pas compatible avec les rapports d'erreur réseau. Pour en savoir plus, consultez les étapes de migration.
- La version 0 n'est pas compatible avec tous les navigateurs et ne le sera pas. La version 1 sera probablement compatible avec plusieurs navigateurs à l'avenir.
Ce qui ne change pas
- Le format et la structure des rapports restent inchangés.
- La requête envoyée par le navigateur au point de terminaison reste une requête
POST
deContent-type
application/reports+json
. - Le mappage de certains points de terminaison à certains types de rapports est possible dans les versions v0 et v1.
- Le rôle du point de terminaison
default
reste inchangé. La version 1 de l'API Reporting n'a aucun impact sur
ReportingObserver
.ReportingObserver
continue d'avoir accès à tous les rapports observables, et leur format est identique.
Toutes les différences entre la version v0 et la version v1
Ancienne API Reporting (v0)Report-To en-tête |
Nouvelle API Reporting (v1)Reporting-Endpoints en-tête |
|
---|---|---|
Prise en charge des navigateurs | Chrome 69 ou version ultérieure, et Edge 69 ou version ultérieure | Chrome 96 et versions ultérieures, Edge 96 et versions ultérieures. Firefox est compatible. Safari n'y voit pas d'inconvénient. Consultez la section Signaux du navigateur. |
Points de terminaison | Envoie des rapports à l'un des plusieurs collecteurs de rapports (plusieurs URL définies par groupe de points de terminaison). | Envoie des rapports à des collecteurs de rapports spécifiques (une seule URL définie par point de terminaison). |
Surface d'API | Utilise l'en-tête `Report-To` pour configurer des groupes de points de terminaison nommés. |
Utilise l'en-tête `Reporting-Endpoints` pour configurer des points de terminaison nommés. |
Types de rapports pouvant être générés via cette API |
|
Inchangé, à l'exception de la journalisation des erreurs réseau (NEL): cette fonctionnalité n'est pas compatible avec la nouvelle API Reporting (v1). |
Portée du rapport | origine. L'en-tête Report-To d'un document affecte les autres documents (pages) de cette origine.
Le champ url d'un rapport varie toujours en fonction du document.
|
Document. L'en-tête Reporting-Endpoints d'un document ne concerne que ce document.
Le champ url d'un rapport varie toujours en fonction du document.
|
Isolation des rapports (groupage) | Les différents documents (pages) ou sites/origines qui génèrent un rapport à peu près au même moment et qui ont le même point de terminaison de création de rapports seront regroupés dans un même lot: ils seront envoyés dans le même message au point de terminaison de création de rapports. |
|
Compatibilité avec l'équilibrage de charge / les priorités | Oui | Non |
Développeurs de points de terminaison: attendez-vous à plus de trafic
Si vous avez configuré votre propre serveur en tant que point de terminaison de création de rapports, ou si vous développez ou gérez un collecteur de rapports en tant que service, attendez-vous à un trafic plus important vers ce point de terminaison.
En effet, les rapports ne sont pas groupés avec l'API Reporting v1, comme ils le sont avec l'API Reporting v0. Par conséquent, à mesure que les développeurs d'applications commenceront à migrer vers la version 1 de l'API Reporting, le nombre de rapports restera similaire, mais le volume de requêtes envoyées au serveur de point de terminaison augmentera.
Développeurs d'applications: migrer vers Reporting-Endpoints
(v1)
Que devez-vous faire ?
L'utilisation de la nouvelle API Reporting (v1) présente plusieurs avantages ✅:
- Les signaux du navigateur sont positifs, ce qui signifie que la compatibilité multinavigateur peut être attendue pour la version 1 (contrairement à la version 0, qui n'est compatible qu'avec Chrome et Edge).
- L'API est plus simple.
- Des outils sont en cours de développement autour de la nouvelle API Reporting (v1).
En gardant cela à l'esprit:
- Si votre site utilise déjà l'API Reporting v0 avec l'en-tête
Report-To
, migrez vers l'API Reporting v1 (voir la procédure de migration). Si votre site utilise déjà la fonctionnalité de création de rapports pour les cas de non-respect de la Content Security Policy, consultez les étapes de migration spécifiques pour les rapports CSP. - Si votre site n'utilise pas encore l'API Reporting et que vous ajoutez maintenant une fonctionnalité de reporting, utilisez la nouvelle API Reporting (v1) (en-tête
Reporting-Endpoints
). Il existe une exception: si vous devez utiliser la journalisation des erreurs réseau, utilisezReport-To
(v0). La journalisation des erreurs réseau n'est actuellement pas compatible avec l'API Reporting v1. Un nouveau mécanisme de journalisation des erreurs réseau sera développé.⏤ En attendant, utilisez la version 0 de l'API Reporting. Si vous avez besoin de la journalisation des erreurs réseau avec d'autres types de rapports, utilisez à la foisReport-To
(v0) etReporting-Endpoints
(v1). La version v0 vous permet de bénéficier de la journalisation des erreurs réseau, tandis que la version v1 vous fournit des rapports sur tous les autres types.
Étapes de migration
L'objectif de cette migration est de ne pas perdre les rapports que vous receviez avec la version 0.
Étape 1 (à faire maintenant): Utilisez les deux en-têtes:
Report-To
(v0) etReporting-Endpoints
(v1).Vous bénéficiez ainsi des avantages suivants:
- Rapports des clients Chrome et Edge plus récents grâce à
Reporting-Endpoints
(v1). - Rapports provenant d'anciens clients Chrome et Edge grâce à
Report-To
(v0).
Les instances de navigateur compatibles avec
Reporting-Endpoints
utiliserontReporting-Endpoints
, et les instances qui ne le sont pas utiliserontReport-To
. Le format de la requête et du rapport est le même pour les versions 0 et 1.- Rapports des clients Chrome et Edge plus récents grâce à
Étape 2 (à faire maintenant) : assurez-vous que l'en-tête
Reporting-Endpoints
est défini sur toutes les réponses susceptibles de générer des rapports.Avec la version 0, vous pouvez choisir de définir des points de terminaison de création de rapports sur certaines réponses uniquement. Les autres documents (pages) de cette origine utiliseront ce point de terminaison "ambiant". Avec la version 1, en raison de la différence de champ d'application, vous devez définir l'en-tête
Reporting-Endpoints
sur toutes les réponses susceptibles de générer des rapports.Étape 3 (à commencer plus tard) : une fois que tous vos utilisateurs ou la plupart d'entre eux ont migré vers des versions ultérieures de Chrome ou d'Edge (96 ou version ultérieure), supprimez
Report-To
(v0) et ne conservez queReporting-Endpoints
.Une exception: si vous avez besoin de rapports de journalisation des erreurs réseau, conservez
Report-To
jusqu'à ce qu'un nouveau mécanisme soit mis en place pour la journalisation des erreurs réseau.
Consultez des exemples de code dans le guide de migration.
Étapes de migration pour les rapports CSP
Il existe deux façons de configurer les rapports de non-respect de la règle Content-Security-Policy:
- Avec l'en-tête CSP seul via la directive
report-uri
. Cette fonctionnalité est compatible avec de nombreux navigateurs, y compris Chrome, Firefox, Safari et Edge. Les rapports sont envoyés avec le type de contenuapplication/csp-report
et ont un format spécifique au CSP. Ces rapports sont appelés "Rapports de niveau 2 du CSP" et ne s'appuient pas sur l'API Reporting. - Avec l'API Reporting, via l'en-tête
Report-To
(ancien) ou le plus récentReporting-Endpoints
(v1). Cette fonctionnalité n'est disponible que dans Chrome et Edge. Les requêtes de rapport ont le même format que les autres requêtes de l'API Reporting et le même type de contenuapplication/reports+json
.
L'utilisation de la première approche (report-uri
uniquement) n'est plus recommandée, et la seconde approche présente quelques avantages. Plus précisément, elle vous permet de configurer les rapports pour tous les types de rapports et de définir un point de terminaison générique (car toutes les requêtes de rapport générées via l'API Reporting⏤CSP et d'autres⏤ ont le même format application/reports+json
.
Toutefois, seuls quelques navigateurs sont compatibles avec report-to
.
Nous vous recommandons donc de conserver report-uri
avec l'approche de l'API Reporting (Report-To
ou mieux, Reporting-Endpoints
) afin de recevoir des rapports de non-respect du CSP de plusieurs navigateurs. Dans un navigateur qui reconnaît report-uri
et report-to
, report-uri
est ignoré si report-to
est présent. Dans un navigateur qui ne reconnaît que report-uri
, seul report-uri
sera pris en compte.
Étape 1 (à faire maintenant): Si vous ne l'avez pas encore ajouté, ajoutez
report-to
à côté dereport-uri
. Les navigateurs qui n'acceptent quereport-uri
(Firefox) utiliserontreport-uri
, et ceux qui acceptent égalementreport-to
(Chrome, Edge) utiliserontreport-to
. Pour spécifier les points de terminaison nommés que vous utiliserez dansreport-to
, utilisez les en-têtesReport-To
etReporting-Endpoints
. Vous recevrez ainsi des rapports provenant à la fois des clients Chrome et Edge plus anciens et plus récents.Étape 3 (à commencer plus tard) : Une fois que tous vos utilisateurs ou la plupart d'entre eux ont migré vers des versions ultérieures de Chrome ou d'Edge (96 ou version ultérieure), supprimez
Report-To
(v0) et ne conservez queReporting-Endpoints
. Conservezreport-uri
pour continuer à recevoir des rapports pour les navigateurs qui ne prennent en charge que cette méthode.
Pour obtenir des exemples de code pour ces étapes, consultez la section Migration des rapports du CSP.
Migration: exemple de code
Présentation
Si vous utilisez l'ancienne API Reporting (v0) pour obtenir des rapports sur les cas de non-respect d'un COOP (en-tête Cross-Origin-Opener-Policy
), d'un COEP (Cross-Origin-Embedder-Policy
) ou d'une règle de document (en-tête Document-Policy
), vous n'avez pas besoin de modifier ces en-têtes de règles lors de la migration vers la version 1 de l'API Reporting. Vous devez migrer de l'ancien en-tête Report-To
vers le nouvel en-tête Reporting-Endpoints
.
Si vous utilisez l'ancienne API Reporting (v0) pour obtenir des rapports sur les cas de non-respect d'un CSP (en-tête Content-Security-Policy
), vous devrez peut-être modifier votre Content-Security-Policy
lors de la migration vers la nouvelle API Reporting (v1).
Migration de base
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"
Notez que la version 1 vous permet toujours d'envoyer des types de rapports spécifiques à des points de terminaison spécifiques. Toutefois, vous ne pouvez avoir qu'une seule URL par point de terminaison.
Observer toutes les pages
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(...) });
Migration des rapports 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: ...
Documentation complémentaire
- Surveiller votre application Web avec l'API Reporting (article principal sur l'API Reporting)
- Spécification: ancienne API Reporting (v0)
- Spécification: nouvelle API Reporting (v1)
Merci à Ian Clelland, Eiji Kitamura et Milica Mihajlija pour leurs commentaires et suggestions sur cet article.