Migrer vers la version 1 de l'API Reporting

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.

Maud Nalpas

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

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

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

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 autres instances passeront à Report-To. Le format de la demande et du rapport est le même pour v0 et v1.

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

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

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 sont compatibles qu'avec report-uri (Firefox) utiliseront report-uri, ainsi que les navigateurs qui assistance report-to(Chrome, Edge) utilisera report-to. Pour spécifier les points de terminaison nommés, vous utiliserez dans report-to, utilisez les en-têtes Report-To et Reporting-Endpoints. Cela garantit que vous obtenez rapports des anciens et nouveaux clients Chrome et Edge.

2. É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 que Reporting-Endpoints. Conserver report-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" }] }

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. 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(...)
});

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

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 .