1# Using the common report collector
2
3To send reports to the collector, configure the reporting API to POST reports
4to the collector's URL. This can be same- or cross- origin with the reporting
5document, as the collector will follow the CORS protocol.
6
7The collector supports both CSP Level 2 (report-uri) reports as well as
8Reporting API reports.
9
10A GET request can be used to retrieve stored reports for analysis.
11
12A POST request can be used to clear reports stored in the server.
13
14Sent credentials are stored with the reports, and can be retrieved separately.
15
16CORS Notes:
17* Preflight requests originating from www2.web-platform.test will be rejected.
18  This allows tests to ensure that cross-origin report uploads are not sent when
19  the endpoint does not support CORS.
20
21## Supported GET parameters:
22 `op`: For GET requests, a string indicating the operation to perform (see
23   below for description of supported operations). Defaults to
24  `retrieve_report`.
25
26 `reportID`: A UUID to associate with the reports sent from this document. This
27   can be used to distinguish between reports from multiple documents, and to
28   provide multiple distinct endpoints for a single document. Either `reportID`
29   or `endpoint` must be provided.
30
31 `endpoint`: A string which will be used to generate a UUID to be used as the
32   reportID. Either `reportID` or `endpoint` must be provided.
33
34 `timeout`: The amount of time to wait, in seconds, before responding. Defaults
35   to 0.5s.
36
37 `min_count`: The minimum number of reports to return with the `retrieve_report`
38   operation. If there have been fewer than this many reports received, then an
39   empty report list will be returned instead.
40
41 `retain`: If present, reports will remain in the stash after being retrieved.
42   By default, reports are cleared once retrieved.
43
44### Operations:
45 `retrieve_report`: Returns all reports received so far for this reportID, as a
46   JSON-formatted list. If no reports have been received, an empty list will be
47   returned.
48
49 `retrieve_cookies`: Returns the cookies sent with the most recent reports for
50   this reportID, as a JSON-formatted object.
51
52 `retrieve_count`: Returns the number of POST requests for reports with this
53   reportID so far.
54
55## Supported POST JSON payload:
56
57  `op`:  For POST requests, a string indicating the operation to perform (see
58    below for description of supported operations).
59
60  `reportIDs`: A list of `reportID`s, each one a UUID associated with reports stored in the server stash.
61
62### Operations
63`DELETE`: Clear all reports associated with `reportID` listed in `reportIDs` list.
64
65### Example usage:
66```
67# Clear reports on the server.
68fetch('/reporting/resources/report.py', {
69  method: "POST",
70  body: JSON.stringify({
71    op: "DELETE",
72    reportIDs: [...] # a list of reportID
73  })
74});
75```
76