# Comment configurer le Reporting API du navigateur (/fr/blog/how-to-set-up-the-reporting-api) Le navigateur sait déjà quand vos politiques de sécurité se déclenchent, quand des requêtes réseau échouent, et quand une page utilise une API sur le point d'être supprimée. La plupart du temps, ce savoir reste dans le navigateur de l'utilisateur et vous ne le voyez jamais. Le Reporting API sert à le faire sortir : quelques lignes de configuration suffisent pour que le navigateur empaquette ces événements en JSON et les envoie à un serveur que vous contrôlez. Ce guide vous emmène de zéro à un endpoint qui reçoit de vrais rapports, à la manière moderne : `Reporting-Endpoints` d'abord, et le `Report-To` déprécié seulement là où vous en avez encore besoin. En bref : déclarez un endpoint avec un header, nommez-le depuis une politique, et le navigateur regroupe puis livre des rapports JSON à votre URL, hors bande. Le reste de ce guide détaille ces trois étapes et explique comment lire ce qui arrive. ## Ce que fait réellement le Reporting API [#ce-que-fait-réellement-le-reporting-api] Il est utile de séparer deux choses. Une politique ou une fonctionnalité de plateforme est le *producteur* : politique de sécurité du contenu (CSP), Cross-Origin-Opener-Policy (COOP), Network Error Logging, un avertissement de deprecation, un crash. Le Reporting API est le *transport* : une file partagée dans le navigateur qui collecte ces rapports et les livre. Le producteur décide de ce qui mérite d'être rapporté, l'API décide comment cela circule. Quand un producteur signale un événement, le navigateur ne l'envoie pas immédiatement. Il collecte le rapport, le regroupe avec d'autres et envoie le lot en POST à votre endpoint, à son propre rythme et indépendamment de la page. C'est tout l'intérêt de ce découplage : un rapport peut encore arriver après que la page a navigué ailleurs ou même planté, car la livraison ne dépend pas de sa survie. Une réserve, pour fixer les attentes : la spec parle d'une livraison au mieux, pas d'un canal garanti. Des rapports peuvent être abandonnés, dédupliqués ou retardés. Traitez donc le flux comme un signal de grande valeur, pas comme un journal d'audit dont vous pourriez prouver l'exhaustivité. Pour le modèle complet, voir [comment fonctionne le Reporting API](/fr/docs/web-security/reporting-api/concepts/how-the-reporting-api-works). ## Étape 1, déclarer un endpoint de reporting [#étape-1-déclarer-un-endpoint-de-reporting] Tout commence par un header de réponse. `Reporting-Endpoints` est une liste d'endpoints nommés, chacun associant un nom à une URL HTTPS. ```http Reporting-Endpoints: main-endpoint="https://.report.centralcsp.com" ``` Deux règles comptent ici. L'URL doit être en HTTPS : le navigateur ignore silencieusement un endpoint non sécurisé, et une faute de frappe ou une URL `http://` fait donc disparaître les rapports sans la moindre erreur. Et le header ne vaut que pour la réponse sur laquelle il est servi : envoyez-le sur chaque page qui doit pouvoir rapporter, pas seulement sur la page d'accueil. Rien ne vous empêche de déclarer plusieurs endpoints et d'acheminer chaque politique vers une URL différente. Vous pouvez aussi déclarer un endpoint spécial nommé `default`, qui récupère les types de rapports sans destination désignée ([deprecations et interventions](/fr/blog/deprecation-intervention-reports), [crashs](/fr/blog/browser-crash-reports)). ```http Reporting-Endpoints: default="https://.report.centralcsp.com", csp-endpoint="https://.report.centralcsp.com" ``` Un producteur reste en dehors de tout cela. [Network Error Logging](/fr/docs/web-security/policies/network-error-logging) ne sait pas lire `Reporting-Endpoints` : le header `NEL` désigne un groupe déclaré dans le header historique [`Report-To`](/fr/docs/web-security/reporting-api/headers/report-to), et Chromium ne livre les erreurs réseau qu'à ces groupes. Si vous les voulez, envoyez `Report-To` en plus de `Reporting-Endpoints`. La syntaxe complète est sur la [référence Reporting-Endpoints](/fr/docs/web-security/reporting-api/headers/reporting-endpoints). ## Étape 2, pointer une politique vers l'endpoint [#étape-2-pointer-une-politique-vers-lendpoint] Déclarer un endpoint ne suffit pas : une politique doit le référencer par son nom. Pour CSP, c'est la directive `report-to`. Démarrez en Report-Only, pour qu'une erreur dans la politique se contente de remonter un rapport au lieu de bloquer, sans casser la page pendant que vous l'ajustez. ```http Reporting-Endpoints: main-endpoint="https://.report.centralcsp.com" ``` ```http Content-Security-Policy-Report-Only: default-src 'self'; report-to main-endpoint ``` Les autres politiques se rattachent à un endpoint de la même façon, avec de petites différences de syntaxe : COOP et COEP utilisent un paramètre `report-to="..."` sur leur header, Integrity-Policy utilise une directive `endpoints=(...)`, et les types de rapports implicites (deprecation, intervention, crash) partent vers l'endpoint `default` sans aucun câblage. ## Étape 3, lire ce qui arrive [#étape-3-lire-ce-qui-arrive] Au moment de la livraison, le navigateur envoie un POST HTTP avec `Content-Type: application/reports+json` et un tableau JSON. Toutes les entrées partagent la même enveloppe, les champs `type`, `url`, `user_agent`, `age` et `body` ; seul le `body` change d'un type de rapport à l'autre. ```json [ { "type": "csp-violation", "age": 53, "url": "https://example.com/", "user_agent": "Mozilla/5.0 ...", "body": { "documentURL": "https://example.com/", "blockedURL": "https://evil.example/script.js", "effectiveDirective": "script-src-elem", "disposition": "report", "statusCode": 200 } } ] ``` Ne soyez pas surpris si le premier rapport met une minute à apparaître. Chromium regroupe les livraisons et les retarde pour économiser la batterie et la bande passante : le reporting n'a rien d'instantané. L'enveloppe, et ce qui la distingue du format hérité à objet unique `application/csp-report` qu'utilise `report-uri`, est détaillée dans [le format de livraison des rapports](/fr/docs/web-security/reporting-api/concepts/report-delivery-format). Si vous préférez vérifier qu'un site en production est bien câblé avant de construire un récepteur, le [vérificateur de configuration du Reporting API](/tools/reporting-api) le fait pour vous. Un bloc d'en-têtes généré qui déclare le point de collecte et y dirige chaque politique ## Où les rapports devraient aller [#où-les-rapports-devraient-aller] Le panorama complet est dans [où vont les rapports du navigateur et comment les recevoir](/fr/blog/where-to-send-csp-reports) ; voici les compromis. Vous pouvez monter votre propre collecteur, et pour une seule politique sur un site à faible trafic, cela suffit très bien. La vraie limite apparaît à l'échelle : le trafic réel produit énormément de rapports, dont beaucoup de doublons sans intérêt, et la valeur n'est pas de les stocker mais de les grouper, de les dédupliquer et d'alerter sur ceux qui comptent. C'est un backend à construire et à maintenir. CentralCSP est ce backend, en tant que service. Pointez l'URL `Reporting-Endpoints` vers lui et il [collecte tous les types de rapports](/fr/docs/platform/monitoring), les groupe, rattache les violations CSP et les hashs de scripts à de vraies causes, et transforme le flux en alertes et en preuves exportables. Vous faites l'économie du collecteur et démarrez directement sur la partie utile. ## Étapes suivantes [#étapes-suivantes] * Passez en revue [tous les types de rapports](/fr/docs/web-security/reporting-api/reports) et ce que chacun vous apprend. * Câblez des politiques précises : [CSP](/fr/docs/web-security/policies/content-security-policy), [COOP](/fr/docs/web-security/policies/cross-origin-opener-policy), [NEL](/fr/docs/web-security/policies/network-error-logging). * Comprenez les deux générations de headers avec [Report-To vs Reporting-Endpoints](/fr/docs/web-security/reporting-api/concepts/report-to-vs-reporting-endpoints). Prêt à collecter depuis le trafic réel plutôt que depuis un endpoint jetable ? [Démarrez un essai gratuit](/register). ## Sources [#sources] * [W3C, Reporting API](https://www.w3.org/TR/reporting-1/) * [W3C, Network Error Logging](https://www.w3.org/TR/network-error-logging/) * [MDN, Reporting-Endpoints](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints) * [MDN, Reporting API](https://developer.mozilla.org/en-US/docs/Web/API/Reporting_API)