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 compatible avec les navigateurs.

Maud Nalpas
Maud Nalpas
X GitHub

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émo et code

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 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.

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 des points de terminaison nommés. Comme la version 0, 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.
v0 (ancienne version)

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.

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 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 de Content-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
  • Obsolescence
  • Intervention
  • Accident
  • COOP/COEP
  • Niveau 3 de Content-Security-Policy (CSP)
  • Journalisation des erreurs réseau (NEL)
Pour en savoir plus sur les types de rapports, consultez l'article sur l'API Reports. 		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.
  • 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 de confidentialité.
  • Les rapports 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 à 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, 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 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 fois Report-To (v0) et Reporting-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.

  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 des anciens clients Chrome et Edge grâce à Report-To (v0).

    Les instances de navigateur compatibles avec Reporting-Endpoints utiliseront Reporting-Endpoints, et les instances qui ne le sont pas utiliseront Report-To. Le format de la requête 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 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.

  3. É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 que Reporting-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 contenu application/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écent Reporting-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 contenu application/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.

  1. Étape 1 (à faire maintenant): Si vous ne l'avez pas encore ajouté, ajoutez report-to à côté de report-uri. Les navigateurs qui n'acceptent que report-uri (Firefox) utiliseront report-uri, et ceux qui acceptent également 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 à la fois des clients Chrome et Edge plus anciens et plus récents.

  2. É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 que Reporting-Endpoints. Conservez report-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

Ancien code (avec la version 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 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'à 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 pourra ressembler à 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 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

Code ancien (avec la version 0), 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 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 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

L'utilisation de report-uri uniquement n'est plus recommandée. Si votre code ressemble à celui ci-dessus, effectuez la migration. Consultez les nouveaux exemples de code ci-dessous (en vert).

Meilleur code ancien, 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"

Il est préférable d'utiliser report-to, le nouveau remplacement de report-uri. Il conserve toujours report-uri pour la rétrocompatibilité. Plusieurs navigateurs ne sont pas compatibles avec report-to, mais le sont avec report-uri.

Il est toutefois possible d'améliorer ce code: il utilise la version 0 de l'API Reporting (en-tête Report-To). Migrer 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 la directive report-uri avec la directive report-to jusqu'à ce que la directive report-to soit compatible avec tous les navigateurs. Consultez le tableau de compatibilité des navigateurs.

Maintenez Report-To à côté de Reporting-Endpoints temporairement. Une fois que la plupart de vos visiteurs Chrome et Edge auront migré vers les versions 96 et ultérieures du navigateur, supprimez Report-To.

Documentation complémentaire

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