Comment fonctionne la Reporting API

La Reporting API sépare ce qui produit un report (une politique comme CSP ou COOP) de ce qui le livre (la file d'attente de reports du navigateur). Une politique signale un événement, le navigateur le collecte, le regroupe avec d'autres, et l'envoie plus tard à votre endpoint, indépendamment de la page. C'est ce découplage qui permet à un report d'arriver encore après que la page a quitté ou planté.

Comment la Reporting API livre les reports

Les producteurs sont les politiques et les fonctionnalités de la plateforme : Content Security Policy, Cross-Origin-Opener-Policy (COOP), Cross-Origin-Embedder-Policy (COEP), Permissions-Policy, Document-Policy, Integrity-Policy, Network Error Logging, et les fonctionnalités implicites qui émettent des reports de dépréciation, d'intervention et de crash. Chacune décide quand quelque chose mérite d'être signalé.

La Reporting API est la machinerie partagée sous-jacente. Elle ne définit aucun comportement de politique qui lui soit propre ; elle se contente de structurer chaque report dans une enveloppe commune, de le mettre en file d'attente et de le livrer. C'est l'idée clé : le même transport achemine une violation CSP, une erreur réseau et un avertissement de dépréciation, donc vous configurez la livraison une seule fois et chaque producteur l'utilise.

Déclarer où vont les reports

Vous déclarez les endpoints avec un seul header de réponse, Reporting-Endpoints, qui associe un nom à une URL HTTPS. Une politique référence ensuite ce nom pour router ses reports.

Reporting-Endpoints: default="https://<Endpoint-ID>.report.centralcsp.com"

CSP nomme un endpoint avec sa directive report-to ; COOP et COEP utilisent un paramètre report-to= ; Integrity-Policy utilise endpoints=() ; et les types de report implicites vont vers l'endpoint de reporting par défaut. La syntaxe complète, ainsi que l'ancien header Report-To dont NEL a encore besoin, se trouvent dans la section Headers.

Mise en file d'attente, batching et livraison

Lorsqu'un report est généré, le navigateur ne l'envoie pas de lui-même. Il ajoute le report à une file d'attente, regroupe les reports en file par endpoint puis par origine, et livre chaque groupe sous la forme d'un unique POST HTTP avec Content-Type: application/reports+json. Une seule livraison peut donc transporter plusieurs reports de types différents.

Le timing dépend du navigateur, pas de la spécification. Chromium regroupe et peut retarder la livraison jusqu'à environ une minute pour économiser la batterie et la bande passante sur mobile, donc un report que vous déclenchez maintenant peut n'arriver qu'après un certain temps. C'est normal ; concevez votre endpoint pour accepter les reports au moment où ils se présentent plutôt que de les attendre en temps réel.

Au mieux possible, pas garanti

La livraison peut aussi s'arrêter. Le navigateur suit les échecs par endpoint, et un endpoint qui échoue de façon répétée, ou qui répond avec un HTTP 410 Gone, est abandonné et cesse de recevoir des reports. Un endpoint qui renvoie des erreurs ne perd donc pas seulement le lot en cours ; il peut être retiré entièrement. Renvoyez un statut 2xx depuis votre récepteur, et utilisez 410 délibérément si vous voulez un jour que le navigateur arrête d'envoyer.

Voir aussi

• Le format de livraison des reports
• Report-To face à Reporting-Endpoints
• Headers
• Collectez et agrégez tous les types de report avec le reporting CentralCSP.

Sources

• W3C, Reporting API
• MDN, Reporting API
• Chrome, the Reporting API