Migrer vers la version 1 de l'API Reporting

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.

Maud Nalpas

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.

• 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 de Content-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

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, utilisez Report-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 fois Report-To (v0) et Reporting-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.

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 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 utiliseront Reporting-Endpoints. 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 v0 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 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.

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

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, tandis que les navigateurs 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 obtenez ainsi des rapports des clients Chrome et Edge, plus anciens ou plus récents.

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