Une nouvelle version de l'API Reporting est disponible. Il est plus respectueux de la confidentialité et plus susceptible d'être pris en charge par tous les navigateurs.
L'API Reporting vous informe des erreurs qui se produisent sur votre site lorsque les visiteurs l'utilisent. Il vous offre une visibilité sur les interventions du navigateur, les plantages du navigateur, les cas de non-respect des règles de sécurité du contenu, les cas de non-respect COOP/COEP, les avertissements d'abandon et plus encore.
Une nouvelle version de l'API Reporting est disponible. La nouvelle API est plus simple et plus susceptible d'être compatible avec tous les navigateurs.
Résumé
Développeurs de sites
Si vous disposez déjà d'une fonctionnalité de reporting pour votre site: passez à la version 1 en utilisant le 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 la fonctionnalité de création de rapports à votre site tout de suite: n'utilisez que 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 création de rapports
Si vous gérez un service de point de terminaison ou si vous exploitez votre propre service, attendez-vous à augmenter le trafic à mesure que vous ou les développeurs externes effectuerez la migration vers la version 1 de l'API Reporting (en-tête Reporting-Endpoints
).
Poursuivez votre lecture pour obtenir des détails et des exemples de code.
Journalisation des erreurs réseau
Un nouveau mécanisme de journalisation des erreurs réseau va être développé. Lorsque cette version sera disponible, passez de Reporting API v0 à 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 v0 et v1
Ce qui change
- La surface d'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 v0, vous pouvez définir des points de terminaison de création de rapports pour certaines réponses uniquement. D'autres documents (pages) de cette origine utiliseront automatiquement ces points de terminaison ambiants.
Avec la version 1, vous devez définir l'en-tête Reporting-Endpoints
pour toutes les réponses susceptibles de générer des rapports.
- Les deux API acceptent les mêmes types de rapports, à une exception près: la version 1 n'est pas compatible avec les rapports d'erreurs réseau. Pour en savoir plus, consultez la procédure de migration.
- La version v0 ne fonctionne pas et ne sera pas compatible avec tous les navigateurs. À l'avenir, la version v1 sera plus susceptible d'être compatible avec plusieurs navigateurs.
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 avec certains types de rapports est compatible avec les versions v0 et 1.
- Le rôle du point de terminaison
default
reste inchangé. La version 1 de l'API Reporting n'a aucune incidence sur le
ReportingObserver
.ReportingObserver
continue d'accéder à tous les rapports observables, et leur format est identique.
Toutes les différences entre v0 et v1
Ancienne API Reporting (v0) En-tête Report-To |
Nouvelle API Reporting (v1) En-tête Reporting-Endpoints |
|
---|---|---|
Prise en charge des navigateurs | Chrome 69+ et Edge 69+. | Chrome 96+ et Edge 96+. Firefox est compatible. Safari ne s'y oppose pas. Consultez Signaux du navigateur. |
Points de terminaison | Envoie des rapports à 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. |
Elle 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 |
|
Non modifié, sauf dans la journalisation des erreurs réseau (NEL): cette fonctionnalité n'est pas prise en charge dans 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 d'un document à l'autre.
|
Document. L'en-tête Reporting-Endpoints d'un document n'affecte que ce document.
Le champ url d'un rapport varie toujours d'un document à l'autre.
|
Isolation des rapports (traitement par lot) | Différents documents (pages) ou sites/origines qui génèrent un rapport au même moment et qui sont associés au même point de terminaison de rapport seront regroupés: ils seront envoyés dans le même message au point de terminaison du reporting. |
|
Compatibilité avec l'équilibrage de charge et 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 à augmenter le trafic vers ce point de terminaison.
En effet, les rapports ne sont pas regroupés avec la version 1 de l'API Reporting, comme c'est le cas avec la version 0 de l'API Reporting. Par conséquent, lorsque 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 vers le 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 version 1 est compatible avec plusieurs navigateurs (contrairement à la version v0 qui n'est compatible qu'avec Chrome et Edge).
- L'API est plus simple.
- Les 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à une fonctionnalité de création de rapports pour les cas de non-respect des règles de sécurité du contenu, vérifiez les étapes de migration spécifiques à la création de rapports CSP. - Si votre site n'utilise pas encore l'API Reporting et que vous ajoutez maintenant une fonctionnalité de création de rapports, utilisez la nouvelle API Reporting (v1) (l'en-tête
Reporting-Endpoints
). Il existe une exception à cette règle: 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é jusqu'à ce qu'il soit disponible, utilisez l'API Reporting v0. Si vous avez besoin de la journalisation des erreurs réseau en plus d'autres types de rapports, utilisez à la foisReport-To
(v0) etReporting-Endpoints
(v1). La version v0 vous fournit la journalisation des erreurs réseau, tandis que la version v1 génère des rapports de tous les autres types.
Étapes de migration
Avec cette migration, votre objectif est de ne pas perdre les rapports que vous obteniez avec la version v0.
É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 nouveaux clients Chrome et Edge grâce à
Reporting-Endpoints
(v1). - Rapports d'anciens clients Chrome et Edge grâce à
Report-To
(v0).
Les instances de navigateur compatibles avec
Reporting-Endpoints
utiliserontReporting-Endpoints
. 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 v0 et 1.- Rapports des nouveaux clients Chrome et Edge 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 v0, vous pouvez choisir de définir des points de terminaison de création de rapports sur certaines réponses uniquement, et d'autres documents (pages) de cette origine utiliseraient 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 de vos utilisateurs ont effectué la mise à jour vers des installations ultérieures de Chrome ou d'Edge (96 et versions ultérieures), supprimez
Report-To
(v0) et ne conservez queReporting-Endpoints
.Une exception: si vous avez besoin des rapports de journalisation des erreurs réseau, conservez
Report-To
jusqu'à ce qu'un nouveau mécanisme soit en place pour la journalisation des erreurs réseau.
Consultez les exemples de code dans le livre de recettes sur la migration.
Étapes de migration pour les rapports CSP
Il existe deux façons de configurer les rapports de violation Content-Security-Policy:
- Avec l'en-tête CSP seul via la directive
report-uri
. Il est compatible avec de nombreux navigateurs, sur Chrome, Firefox, Safari et Edge. Les rapports sont envoyés avec le type de contenuapplication/csp-report
et utilisent un format spécifique à CSP. Ces rapports sont appelés "Rapports CSP de niveau 2" et ne s'appuient pas sur l'API Reporting. - Avec l'API Reporting, via l'en-tête
Report-To
(ancien) ouReporting-Endpoints
plus récent (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
.
La première approche (report-uri
uniquement) n'est plus recommandée. La seconde présente certains avantages. Vous pouvez ainsi configurer la création de rapports pour tous les types de rapports de manière centralisée, et définir un point de terminaison générique (car toutes les demandes de rapports générées via l'API Reporting CSP et d'autres demandes ont le même format application/reports+json
).
Cependant, seuls certains navigateurs sont compatibles avec report-to
.
Il est donc recommandé 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 des CSP depuis plusieurs navigateurs. Dans un navigateur qui reconnaît report-uri
et report-to
, report-uri
sera ignoré si report-to
est présent. Dans un navigateur qui ne reconnaît que report-uri
, seul report-uri
est pris en compte.
Étape 1 (à faire maintenant): si vous ne l'avez pas encore fait, ajoutez
report-to
à côté dereport-uri
. Les navigateurs qui ne prennent en charge quereport-uri
(Firefox) utiliserontreport-uri
, tandis que les navigateurs qui prennent également en chargereport-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 obtenez ainsi des rapports des clients Chrome et Edge, plus anciens ou plus récents.Étape 3 (commencer plus tard) : une fois que tous vos utilisateurs ou la plupart de vos utilisateurs ont effectué la mise à jour vers des installations ultérieures de Chrome ou d'Edge (96 et versions ultérieures), supprimez
Report-To
(v0) et ne conservez queReporting-Endpoints
. Conservezreport-uri
afin de recevoir des rapports pour les navigateurs qui ne l'acceptent que.
Consultez des exemples de code pour ces étapes dans Migration des rapports CSP.
Migration: exemple de code
Présentation
Si vous utilisez l'ancienne API Reporting (v0) pour obtenir des rapports de non-respect des règles pour un COOP (en-tête Cross-Origin-Opener-Policy
), un COEP (Cross-Origin-Embedder-Policy
) ou une règle de document (en-tête Document-Policy
): vous n'avez pas besoin de modifier ces en-têtes de règles vous-même lors de la migration vers la version 1 de l'API Reporting. Vous devez passer de l'ancien en-tête Report-To
au nouvel en-tête Reporting-Endpoints
.
Si vous utilisez l'ancienne API Reporting (v0) pour obtenir des rapports de non-respect pour un fournisseur de services cloud (en-tête Content-Security-Policy
), vous devrez peut-être modifier votre Content-Security-Policy
lors de votre 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 qu'avec la version 1, vous pouvez toujours 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: ...
Complément d'informations
- Contrôler 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)
Image héros de Nine Koepfer / @enka80 sur Unsplash, modifiée. Nous remercions Ian Clelland, Eiji Kitamura et Milica Mihajlija pour leurs avis et suggestions sur cet article.