Une nouvelle version de l'API Reporting est disponible. Elle est plus privée et est plus susceptible d'être compatible avec tous les navigateurs.
L'API Reporting vous informe des erreurs qui se produisent sur votre site lorsque les visiteurs l'utilisent. Il donne une meilleure visibilité sur les interventions du navigateur, les plantages du navigateur, les violations des règles de sécurité du contenu, Non-respect des règles COOP/COEP, avertissements d'abandon, etc.
Une nouvelle version de l'API Reporting est disponible. La nouvelle API est plus simple et plus susceptible compatible avec tous les navigateurs.
Résumé
Développeurs de sites
Si vous disposez déjà d'une fonctionnalité de création de rapports pour votre site: passez à la version 1 en utilisant le nouvel en-tête.
(Reporting-Endpoints
), mais conserver l'ancien en-tête pendant un certain temps (Report-To
).
Consultez Migration: exemple de code.
Si vous ajoutez une fonctionnalité de création de rapports à votre site à l'instant: 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
générer des rapports.
Développeurs de services de reporting
Si vous gérez un service de point de terminaison ou si vous utilisez votre propre service, attendez-vous à plus de trafic à mesure que vous
ou des développeurs externes migrent vers l'API Reporting v1 (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é. Passez ensuite 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 du site de démonstration
Différences entre 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
{0 utilise l'en-tête Report-To
pour configurer des groupes de points de terminaison nommés et la directive report-to
dans d'autres en-têtes pour référencer ces groupes de points de terminaison.
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default" Document-Policy: ...; report-to main-endpoint
v1 utilise l'en-tête Reporting-Endpoints
pour configurer les
points de terminaison. Comme la version v0, elle utilise la directive report-to
dans d'autres en-têtes pour référencer ces groupes de points de terminaison.
- La portée du rapport est différente.
Avec v0, vous ne pouvez définir des points de terminaison de création de rapports que pour certaines réponses. D'autres documents (pages) à ce sujet utiliserait 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
rapports.
- Les deux API acceptent les mêmes types de rapports, à une exception près: la v1 n'est pas compatible avec les rapports d'erreur réseau. Pour en savoir plus, consultez la procédure de migration.
- v0 ne l'est pas et ne sera pas compatible avec tous les navigateurs. v1 a plus de chances d'être compatible dans 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 avec 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 aucune incidence sur la
ReportingObserver
.ReportingObserver
a toujours accès à tous les rapports observables, qui sont au format identiques.
Toutes les différences entre les versions 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 ou version ultérieure et Edge 69 ou version ultérieure. | Chrome 96 ou version ultérieure et Edge 96 ou version ultérieure. Firefox prend en charge. Safari ne s'oppose pas à ce qu'il fait. 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 | Il utilise l'en-tête `Report-To` pour configurer des groupes de points de terminaison nommés. |
Il 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 |
|
Aucun changement, hormis pour la journalisation des erreurs réseau (NEL): cette option 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 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 à peu près au même moment et qui ont le même point de terminaison de création de rapports seront regroupés: 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 comme point de terminaison de création de rapports, ou si vous développez ou gérez le collecteur de rapports en tant que service, d'attendre plus de trafic vers ce point de terminaison.
En effet, les rapports ne sont pas regroupés avec l'API Reporting v1, contrairement à la version 0. Par conséquent, À mesure que les développeurs d'applications commenceront à migrer vers l'API Reporting v1, le nombre de rapports augmentera restent similaires, mais le volume de requêtes adressées au serveur de points de terminaison va augmenter.
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 Edge).
- L'API est plus simple.
- Les outils sont développés autour de la nouvelle API Reporting (v1).
Gardez cela à l'esprit:
- Si votre site utilise déjà la version 0 de l'API Reporting avec l'en-tête
Report-To
, migrez vers la API Reporting v1 (voir les étapes de migration). Si votre site utilise déjà de création de rapports pour les cas de non-respect des règles de sécurité du contenu, consultez la procédure de migration pour la création de rapports CSP. - Si votre site n'utilise pas encore l'API Reporting et que vous ajoutez maintenant la fonctionnalité de création de rapports:
Utilisez la nouvelle API Reporting (v1) (l'en-tête
Reporting-Endpoints
). Il existe une exception ceci: si vous devez utiliser la journalisation des erreurs réseau, utilisezReport-To
(v0). 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 être développée ⏤ jusqu'à ce qu'elle soit disponible, utilisez l'API Reporting v0. 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). v0 vous donne la journalisation des erreurs réseau et la v1 vous donne des rapports de tous les autres types.
Étapes de migration
L'objectif de cette migration est de ne pas perdre les rapports que vous aviez l'habitude d'obtenir avec 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 clients Chrome et Edge plus récents grâce à
Reporting-Endpoints
(v1). - Rapports des anciens clients Chrome et Edge grâce à
Report-To
(v0).
Les instances de navigateur compatibles avec
Reporting-Endpoints
utiliserontReporting-Endpoints
, et Les autres instances passeront àReport-To
. Le format de la demande et du rapport est le même pour v0 et v1.- 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 qui peuvent générer des rapports.Avec la version v0, vous pouviez choisir de définir les points de terminaison des rapports uniquement pour certaines réponses et d'autres documents (pages) pour cette origine utiliseraient cette "ambiance ambiante" point de terminaison unique. Avec la version 1, en raison de la différence champ d'application, vous devez définir l'en-tête
Reporting-Endpoints
sur toutes les réponses susceptibles de générer rapports.Étape 3 (recommencer plus tard) : Une fois que la totalité ou la plupart de vos utilisateurs sont passés à une version ultérieure de Chrome ou d'Edge (96 et versions ultérieures), supprimer
Report-To
(v0) et ne conserver queReporting-Endpoints
.Exception: si vous avez besoin des rapports de journalisation des erreurs réseau, conservez
Report-To
jusqu'à est en place pour la journalisation des erreurs réseau.
Consultez des exemples de code dans le livre de recettes pour la migration.
Procédure de migration des rapports CSP
Il existe deux façons d'utiliser Content-Security-Policy vous pouvez configurer les signalements de non-respect des règles:
- Avec l'en-tête CSP seul via la directive
report-uri
. Il est compatible avec de nombreux navigateurs, Chrome, Firefox, Safari et Edge. Les rapports sont envoyés avec le type de contenuapplication/csp-report
et avoir un format spécifique à CSP. Ces rapports sont appelés "Rapports de niveau 2 de la CSP" et à faire ne dépendent pas de l'API Reporting. - Avec l'API Reporting, utilisez l'en-tête
Report-To
(ancien) ou le plus récent.Reporting-Endpoints
(v1). Cette fonctionnalité n'est compatible qu'avec Chrome et Edge. Les demandes de rapport sont 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 méthode (report-uri
uniquement) n'est plus recommandée. La seconde méthode présente quelques avantages. En particulier, vous pouvez configurer des rapports pour tous les types de rapports à l'aide d'une seule méthode, et définir un point de terminaison générique (toutes les demandes de rapports 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
parallèlement à l'approche de l'API Reporting (Report-To
ou mieux, Reporting-Endpoints
) afin de recevoir des rapports de non-respect 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
sera 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 sont compatibles qu'avecreport-uri
(Firefox) utiliserontreport-uri
, ainsi que les navigateurs qui assistancereport-to
(Chrome, Edge) utiliserareport-to
. Pour spécifier les points de terminaison nommés, vous utiliserez dansreport-to
, utilisez les en-têtesReport-To
etReporting-Endpoints
. Cela garantit que vous obtenez rapports des anciens et nouveaux clients Chrome et Edge.Étape 3 (recommencer plus tard) : Une fois que la totalité ou la plupart de vos utilisateurs sont passés à une version ultérieure de Chrome ou d'Edge (96 et versions ultérieures), supprimer
Report-To
(v0) et ne conserver queReporting-Endpoints
. Conserverreport-uri
pour que vous continuiez à recevoir des rapports pour les navigateurs qui ne sont compatibles qu'avec ce navigateur.
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 recevoir des signalements de non-respect pour un COOP
(en-tête Cross-Origin-Opener-Policy
), un code 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 eux-mêmes lors de la migration.
à l'API Reporting v1. Vous devez passer de l'ancien en-tête Report-To
au nouveau.
Reporting-Endpoints
.
Si vous utilisez l'ancienne API Reporting (v0) pour recevoir des rapports de non-respect pour une CSP
(en-tête Content-Security-Policy
), vous devrez peut-être ajuster votre Content-Security-Policy
dans le cadre 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" }] }
Si vous disposez déjà de la fonctionnalité de création de rapports sur votre site, conservez Report-To
uniquement temporairement
(jusqu'à ce que la plupart des clients Chrome et Edge aient été mis à jour) pour éviter de perdre des rapports.
Si vous avez besoin de la journalisation des erreurs réseau, conservez Report-To
jusqu'au remplacement de la journalisation des erreurs réseau
devient disponible.
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Voici à quoi ressemblera votre code à l'avenir, une fois que la plupart des clients Chrome et Edge auront été mis à jour et seront compatibles avec la version 1 de l'API.
Notez qu'avec la version 1, vous pouvez toujours envoyer des types de rapports spécifiques à des points de terminaison spécifiques. Mais vous ne peut avoir qu'une seule URL par point de terminaison.
Observation de toutes les pages
app.get("/", (request, response) => { response.set("Report-To", …) response.render(...) }); app.get("/page1", (request, response) => { response.render(...) });
Avec v0, vous ne pouvez définir des points de terminaison de création de rapports que pour certaines réponses. Autre
documents (pages) de cette origine utilisent automatiquement ces points de terminaison ambiants. Ici, les points de terminaison définis
pour "/"
sont utilisés pour toutes les réponses, par exemple pour 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(...) });
Avec la version 1, vous devez définir l'en-tête Reporting-Endpoints
sur toutes
des réponses susceptibles de générer des rapports.
Migration des rapports CSP
Content-Security-Policy: ...; report-uri https://reports.example/main
L'utilisation de report-uri
uniquement n'est plus
recommandé.
Si votre code se présente comme dans l'exemple ci-dessus, migrez. Consultez les exemples de la section "Nouveau code" ci-dessous (en vert).
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Report-To: main-endpoint="https://reports.example/main"
C'est mieux: ce code utilise report-to, le plus récent de remplacement pour
report-uri. Il conserve toujours l'URI du rapport pour assurer la rétrocompatibilité. plusieurs
les navigateurs ne sont pas compatibles
report-to
mais prenez en charge
report-uri
Cela pourrait être mieux: ce code utilise l'API Reporting v0 (en-tête Report-To
). Migrer vers la v1: consultez les
Nouveau code exemples ci-dessous (en vert).
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Reporting-Endpoints: main-endpoint="https://reports.example/main" Report-To: ...
Conservez l'instruction report-uri
parallèlement à l'instruction report-to
jusqu'à l'instruction report-to
est compatible avec tous les navigateurs. Consultez la liste des navigateurs compatibles
tableau.
Conserver temporairement Report-To
avec Reporting-Endpoints
. Une fois que la plupart des fonctionnalités
les visiteurs sont passés à plus de 96 versions de navigateur. Supprimez 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)
Image principale par Nine Koepfer / @enka80 sur Unsplash (modification) Merci beaucoup à Ian Clelland, Eiji Kitamura et Milica Mihajlija pour leurs avis et leurs suggestions à ce sujet .