Migrer vers la version 1 de l'API Reporting

Une nouvelle version de l'API Reporting est disponible. Il est plus privé et plus susceptible d'être pris en charge par les navigateurs.

Maud Nalpas

Attention : Cet article explique comment migrer vers la nouvelle version de l'API Reporting (v1). Si vous ne connaissez pas l'API Reporting ou si vous avez besoin d'exemples d'utilisation détaillés, consultez plutôt l'article principal sur l'API Reporting.

L'API Reporting vous informe des erreurs qui se produisent sur votre site lorsque les visiteurs l'utilisent. Il vous permet de visualiser les interventions du navigateur, les plantages du navigateur, les violations de la règle Content-Security-Policy, les violations de COOP/COEP, les avertissements de suppression 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 les navigateurs.

Remarque : L'ancienne API Reporting est nommée Reporting API v0. La nouvelle API Reporting s'appelle Reporting API v1.

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 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 des fonctionnalités de reporting à 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 si vous en utilisez un, attendez-vous à plus de trafic lorsque vous ou des développeurs externes migrerez vers l'API Reporting v1 (en-tête Reporting-Endpoints).

Lisez la suite pour en savoir plus et découvrir un exemple de code.

Journalisation des erreurs réseau

Attention : Si vous utilisez Network Error Logging, continuez à utiliser Report-To (v0), car Network Error Logging n'est pas compatible avec l'API Reporting v1.

Un nouveau mécanisme de journalisation des erreurs réseau sera développé. Une fois qu'il sera disponible, passez de l'API Reporting v0 à 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 les versions v0 et v1

Ce qui change

• La surface de l'API est différente.

v0 (ancienne version)

 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 les groupes de points de terminaison nommés et la directive report-to dans d'autres en-têtes pour faire référence à ces groupes de points de terminaison.

v1 (nouveau)

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

La version 1 utilise l'en-tête Reporting-Endpoints pour configurer les points de terminaison nommés. Comme la version 0, elle utilise la directive report-to dans d'autres en-têtes pour faire référence à ces groupes de points de terminaison.

• La portée du rapport est différente.

v0 (ancienne version)

Avec la version 0, vous pouvez définir des points de terminaison de reporting sur certaines réponses uniquement. Les autres documents (pages) de cette origine utiliseraient automatiquement ces points de terminaison ambiants.

v1 (nouveau)

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 sur les erreurs réseau. Pour en savoir plus, consultez les étapes de la migration.
• La version 0 n'est pas et ne sera pas compatible avec les navigateurs. La version 1 a plus de chances d'être 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 de Content-type application/reports+json.
• Le mappage de certains points de terminaison à certains types de rapports est compatible avec les versions v0 et v1.
• Le rôle du point de terminaison default reste inchangé.

• L'API Reporting v1 n'a aucune incidence sur ReportingObserver. ReportingObserver continue d'avoir accès à tous les rapports observables, et leur format est identique.

Toutes les différences entre les versions v0 et v1

	Ancienne API Reporting (v0) Report-To header	Nouvelle API Reporting (v1) Reporting-Endpoints header
Prise en charge des navigateurs	Chrome 69+ et Edge 69+.	Chrome 96+ et Edge 96+ sont compatibles. Firefox est également compatible. Safari n'émet aucune objection. 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 les groupes de points de terminaison nommés.	Utilise l'en-tête `Reporting-Endpoints` pour configurer les points de terminaison nommés.
Types de rapports pouvant être générés avec cette API	Obsolescence Intervention Accident COOP/COEP Content-Security-Policy Level 3 (CSP Level 3) Journalisation des erreurs réseau (NEL) Pour en savoir plus sur les types de rapports, consultez l'article sur l'API Reporting.	Aucun changement, sauf pour Network Error Logging (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 selon le document.	Document.  L'en-tête Reporting-Endpoints d'un document n'affecte que ce document. Le champ url d'un rapport varie toujours selon le document.
Isolation des rapports (regroupement)	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 rapport seront regroupés : ils seront envoyés dans le même message au point de terminaison de rapport.	Les rapports provenant de différents documents (pages) ne sont jamais envoyés ensemble. Même si deux documents (pages) de la même origine génèrent un rapport en même temps, pour le même point de terminaison, ils ne seront pas regroupés. Il s'agit d'un mécanisme permettant de limiter les attaques visant la confidentialité. Les signalements provenant du même document (page) peuvent être envoyés ensemble.
Compatibilité avec l'équilibrage de charge / les priorités	Oui	Non

Développeurs de points de terminaison : attendez-vous à un trafic plus important

Si vous avez configuré votre propre serveur comme 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 à ce que le trafic vers ce point de terminaison augmente.

En effet, les rapports ne sont pas regroupés par lots avec l'API Reporting v1, contrairement à l'API Reporting v0. Par conséquent, à mesure que les développeurs d'applications commenceront à migrer vers l'API Reporting v1, 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 version 1 devrait être compatible avec plusieurs navigateurs (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).

Voici quelques points à retenir :

• Si votre site utilise déjà l'API Reporting v0 avec l'en-tête Report-To, migrez vers l'API Reporting v1 (consultez la procédure de migration). Si votre site utilise déjà des fonctionnalités de création de rapports pour les violations 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 des fonctionnalités de reporting, utilisez la nouvelle API Reporting (v1) (l'en-tête Reporting-Endpoints). Il existe une exception à cette règle : si vous devez utiliser Network Error Logging, utilisez Report-To (v0). La journalisation des erreurs réseau n'est actuellement pas prise en charge dans l'API Reporting v1. Un nouveau mécanisme de journalisation des erreurs réseau sera développé. En attendant, utilisez l'API Reporting v0. Si vous avez besoin de Network Error Logging en plus d'autres types de rapports, utilisez les deux Report-To (v0) et Reporting-Endpoints (v1). v0 vous donne Network Error Logging et v1 vous donne des rapports de tous les autres types.

Procédure de migration

L'objectif de cette migration est de ne pas perdre les rapports que vous receviez avec la version 0.

Remarque : Étant donné que seules les versions de Chrome et d'Edge sont compatibles avec l'API Reporting v0, vous n'avez pas besoin de vous concentrer sur les autres navigateurs lors de votre migration vers la version 1. Toutefois, gardez à l'esprit qu'une compatibilité plus large avec les navigateurs pourrait être disponible à l'avenir. Pour le moment, il n'existe aucun bug de suivi pour ces navigateurs, mais cela peut changer.

1. Étape 1 (à faire maintenant) : Utilisez les deux en-têtes : Report-To (v0) et Reporting-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 utiliseront Reporting-Endpoints, et celles qui ne le sont pas utiliseront Report-To. Le format de la demande et du rapport est le même pour les versions 0 et 1.

2. Étape 2 (à faire maintenant) : Assurez-vous que l'en-tête Reporting-Endpoints est défini pour toutes les réponses susceptibles de générer des rapports.

   Avec la version 0, vous pouviez 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 portée, vous devez définir l'en-tête Reporting-Endpoints sur toutes les réponses susceptibles de générer des rapports.

3. Étape 3 (à commencer plus tard) : Une fois que tous vos utilisateurs ou la plupart d'entre eux ont installé une version ultérieure de Chrome ou d'Edge (96 ou version ultérieure), supprimez Report-To (v0) et ne conservez que Reporting-Endpoints.

   Une exception : si vous avez besoin de rapports Network Error Logging, conservez Report-To jusqu'à ce qu'un nouveau mécanisme soit en place pour Network Error Logging.

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 sur les cas de non-respect de Content-Security-Policy :

• Avec l'en-tête CSP seul via la directive report-uri. Il est compatible avec de nombreux navigateurs, dont Chrome, Firefox, Safari et Edge. Les rapports sont envoyés avec le type de contenu application/csp-report et ont 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, c'est via l'en-tête Report-To (ancien) ou le nouvel en-tête Reporting-Endpoints (v1). Cette fonctionnalité n'est disponible que dans Chrome et Edge. Les demandes de rapports ont le même format que les autres demandes de l'API Reporting et le même type de contenu application/reports+json.

L'utilisation de la première approche (report-uri uniquement) n'est plus recommandée, tandis que la seconde présente plusieurs avantages. En particulier, il vous permet de configurer les rapports de tous les types de rapports de la même manière et de 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 autres, ont le même format application/reports+json).

Toutefois, seuls quelques navigateurs sont compatibles avec report-to. Il est donc recommandé de conserver report-uri en plus de l'approche de l'API Reporting (Report-To ou mieux, Reporting-Endpoints) afin d'obtenir des rapports sur les violations de la CSP provenant de 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.

1. Étape 1 (à faire maintenant) : Si vous ne l'avez pas encore fait, ajoutez report-to à côté de report-uri. Les navigateurs qui ne prennent en charge que report-uri (Firefox) utiliseront report-uri, et ceux qui prennent également en charge report-to(Chrome, Edge) utiliseront report-to. Pour spécifier les points de terminaison nommés que vous utiliserez dans report-to, utilisez les en-têtes Report-To et Reporting-Endpoints. Vous recevrez ainsi des rapports provenant d'anciens et de nouveaux clients Chrome et Edge.

2. Étape 3 (à commencer plus tard) : Une fois que tous vos utilisateurs ou la plupart d'entre eux ont installé une version ultérieure de Chrome ou d'Edge (96 ou version ultérieure), supprimez Report-To (v0) et ne conservez que Reporting-Endpoints. Conservez report-uri pour continuer à recevoir des rapports pour les navigateurs qui ne le prennent en charge.

Consultez les 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 sur les cas de non-respect pour un en-tête COOP (Cross-Origin-Opener-Policy), COEP (Cross-Origin-Embedder-Policy) ou de règle relative aux documents (Document-Policy), vous n'avez pas besoin de modifier ces en-têtes de règle lorsque vous migrez vers l'API Reporting v1. 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 pour un CSP (en-tête Content-Security-Policy), vous devrez peut-être ajuster votre Content-Security-Policy lors de votre migration vers la nouvelle API Reporting (v1).

Migration de base

Ancien code (avec v0)

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

Nouveau code (code de transition avec v0 et v1)

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 votre site dispose déjà d'une fonctionnalité de création de rapports, conservez Report-To temporairement uniquement (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'à ce que le remplacement de la journalisation des erreurs réseau soit disponible.

Nouveau code (avec la version 1 uniquement)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Voici à quoi votre code pourrait ressembler à l'avenir, une fois que la plupart des clients Chrome et Edge auront été mis à jour et seront compatibles avec l'API v1.

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

Ancien code (avec v0), par exemple avec Express

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

Avec la version 0, vous pouvez définir des points de terminaison de reporting sur certaines réponses uniquement. Les autres 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.

Nouveau code (avec la version 1), par exemple avec Express

// 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 les réponses susceptibles de générer des rapports.

Migration des rapports CSP

Ancien code, avec report-uri uniquement

Content-Security-Policy: ...; report-uri https://reports.example/main

Il n'est plus recommandé d'utiliser uniquement report-uri. Si votre code ressemble à celui ci-dessus, migrez-le. Consultez les nouveaux exemples de code ci-dessous (en vert).

Meilleur code hérité, avec report-uri et la directive report-to avec l'en-tête Report-To (v0)

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 nouveau remplacement de report-uri. Il conserve report-uri pour la rétrocompatibilité. En effet, plusieurs navigateurs ne sont pas compatibles avec report-to, mais le sont avec report-uri.

Toutefois, ce code pourrait être amélioré, car il utilise la version 0 de l'API Reporting (en-tête Report-To). Migrez vers la version 1 : consultez les exemples de "Nouveau code" ci-dessous (en vert).

Nouveau code, avec report-uri et la directive report-to avec l'en-tête Reporting-Endpoints (v1)

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 à côté de l'instruction report-to jusqu'à ce que l'instruction report-to soit compatible avec tous les navigateurs. Consultez le tableau de compatibilité des navigateurs.

Gardez Report-To à côté de Reporting-Endpoints pendant un moment. Une fois que la plupart de vos visiteurs Chrome et Edge sont passés à la version 96 ou ultérieure de leur 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)

Merci beaucoup à Ian Clelland, Eiji Kitamura et Milica Mihajlija pour leurs commentaires et suggestions sur cet article.