# Comment fonctionne la Reporting API (/fr/docs/web-security/reporting-api/concepts/how-the-reporting-api-works)



La Reporting API sépare ce qui produit un report (une politique comme [CSP](/fr/docs/web-security/policies/content-security-policy) ou [COOP](/fr/docs/web-security/policies/cross-origin-opener-policy)) 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 [#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 [#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.

```http
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](/fr/docs/web-security/reporting-api/concepts/default-endpoint). La syntaxe complète, ainsi que l'ancien
header `Report-To` dont NEL a encore besoin, se trouvent dans la section
[Headers](/fr/docs/web-security/reporting-api/headers).

## Mise en file d'attente, batching et livraison [#mise-en-file-dattente-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.

```mermaid
sequenceDiagram
  participant Policy as "Policy (CSP, COOP, NEL)"
  participant Browser as "Browser queue"
  participant Endpoint as "Your endpoint"
  Policy->>Browser: event occurs, report generated
  Note over Browser: queued and batched<br/>out of band, can be delayed
  Browser->>Endpoint: POST batch as application/reports+json
  Note over Browser,Endpoint: best-effort, no guaranteed retry
```

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 [#au-mieux-possible-pas-garanti]

<Callout type="info">
  La spécification est explicite : la livraison est au mieux possible. Le reporting n'est pas un canal de communication fiable, et aucun mécanisme de nouvelle tentative n'est défini, alors ne construisez pas de logique qui dépende de l'arrivée de chaque report.
</Callout>

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 [#voir-aussi]

* [Le format de livraison des reports](/fr/docs/web-security/reporting-api/concepts/report-delivery-format)
* [Report-To face à Reporting-Endpoints](/fr/docs/web-security/reporting-api/concepts/report-to-vs-reporting-endpoints)
* [Headers](/fr/docs/web-security/reporting-api/headers)
* Collectez et agrégez tous les types de report avec [le reporting CentralCSP](/fr/docs/platform/monitoring).

## Sources [#sources]

* [W3C, Reporting API](https://www.w3.org/TR/reporting-1/)
* [MDN, Reporting API](https://developer.mozilla.org/en-US/docs/Web/API/Reporting_API)
* [Chrome, the Reporting API](https://developer.chrome.com/docs/capabilities/web-apis/reporting-api)