Skip to content

Commit 877de49

Browse files
hamishwilleehamishwillee
committed
Reporting API top level restructure
1 parent f3ac8b9 commit 877de49

1 file changed

Lines changed: 41 additions & 38 deletions

File tree

  • files/en-us/web/api/reporting_api

‎files/en-us/web/api/reporting_api/index.md‎

Lines changed: 41 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -28,33 +28,25 @@ There are several different features and problems on the web platform that gener
2828
- Occurrence of crashes.
2929
- Occurrence of user-agent interventions (when the browser blocks something your code is trying to do because it is deemed a security risk for example, or just plain annoying, like auto-playing audio).
3030

31-
The purpose of the Reporting API is to provide a consistent reporting mechanism that can be used to make such information available to developers in the form of reports represented by JavaScript objects. There are a few ways to use it, which are detailed in the sections below.
31+
The purpose of the Reporting API is to provide a consistent reporting mechanism that can be used to make such information available to developers in the form of reports represented by JavaScript objects.
3232

33-
### Reporting server endpoints
34-
35-
Each unique origin you want to get reports for can be given a series of "endpoints", which are named URLs (or groups of URLs) that can be sent reports from a user agent.
36-
A reporting server at these endpoints can collect the reports, and process and present them as needed by your application.
33+
Reports can be obtained within a page using JavaScript via reporting observers, or can be sent to a remote server endpoint.
34+
The types of reports and the two reporting approaches are detailed in the sections below.
3735

38-
The {{httpheader("Reporting-Endpoints")}} HTTP header is used to specify details about the different endpoints that a user-agent has available to it for delivering reports.
39-
The endpoints can then be used on particular HTTP response headers to indicate the specific endpoint (or in some cases endpoints) that will be used for the associated report.
40-
The directive or parameter used to specify an endpoint depends on the header.
41-
For example, the CSP {{CSP("report-to")}} directive can be used on the {{HTTPHeader("Content-Security-Policy")}} or {{HTTPHeader("Content-Security-Policy-Report-Only")}} HTTP headers to specify the endpoint that CSP violation reports should be sent to, while the [`endpoints`](/en-US/docs/Web/HTTP/Reference/Headers/Integrity-Policy#endpoints) field is used on {{httpheader("Integrity-Policy")}} or {{httpheader("Integrity-Policy-Report-Only")}} to specify where to send integrity-policy violation reports.
42-
43-
Report types that don't have an associated HTTP header, such as `crash`, `deprecation`, and `intervention` reports, will usually send reports to the "default reporting endpoint".
44-
This is just an endpoint named "default" specified using the `Reporting-Endpoints` header.
36+
### Report types
4537

46-
> [!NOTE]
47-
> There is no absolute guarantee of report delivery — a report could still fail to be collected if a serious error occurs.
38+
Reports sent to reporting observers are instances of dictionary objects, such as {{domxref("COEPViolationReport")}}, {{domxref("DeprecationReport")}}, {{domxref("IntegrityViolationReport")}}, {{domxref("InterventionReport")}}, {{domxref("CSPViolationReport")}}, and {{domxref("PermissionsPolicyViolationReport")}}.
39+
These all have an origin `url`, a `type`, and a `body` that is specific to the report type.
40+
The type of report can be determined from its `type` property, which for the reports above would be `coep`, `deprecation`, `integrity-violation`, `intervention`, `csp-violation`, and `permissions-policy-violation`.
4841

49-
The reports themselves are sent to the target endpoint by the user agent in a `POST` operation with a {{HTTPHeader("Content-Type")}} of `application/reports+json`.
50-
They are serializations of the corresponding dictionary for each [report type](#report_types).
51-
For example, CSP violation reports are a serialization of a {{domxref("CSPViolationReport")}} object.
42+
Reports sent to reporting endpoints and reporting observers are essentially the same.
43+
The only difference is that server reports are JSON serializations of the objects that have additional `user_agent` and `age` fields.
5244

53-
Reports sent to endpoints can be retrieved independently of the running of the websites they relate to, which is useful — a crash for example could bring down a website and stop anything running, but a report could still be obtained to give the developer some clues as to why it happened.
45+
A list of documented report types and their corresponding report dictionary are given in the [`options.types`](/en-US/docs/Web/API/ReportingObserver/ReportingObserver#types) parameter passed to the `ReportingObserver()` constructor.
5446

5547
### Reporting observers
5648

57-
Reports can also be obtained via {{domxref("ReportingObserver")}} objects created via JavaScript inside the website you are aiming to get reports on.
49+
Reports can be obtained via {{domxref("ReportingObserver")}} objects created via JavaScript inside the website you are aiming to get reports on.
5850
This method is not as failsafe as sending reports to the server because any page crash could stop you retrieving the reports — but it is easier to set up, and more flexible.
5951

6052
A `ReportingObserver` object is created using the {{domxref("ReportingObserver.ReportingObserver", "ReportingObserver()")}} constructor, which is passed two parameters:
@@ -64,16 +56,39 @@ A `ReportingObserver` object is created using the {{domxref("ReportingObserver.R
6456

6557
Methods are then available on the observer to start collecting reports ({{domxref("ReportingObserver.observe()")}}), retrieve the reports currently in the report queue ({{domxref("ReportingObserver.takeRecords()")}}), and disconnect the observer so it can no longer collect records ({{domxref("ReportingObserver.disconnect()")}}).
6658

67-
### Report types
59+
### Reporting server endpoints
6860

69-
Reports sent to reporting observers are instances of dictionary objects, such as {{domxref("COEPViolationReport")}}, {{domxref("DeprecationReport")}}, {{domxref("IntegrityViolationReport")}}, {{domxref("InterventionReport")}}, {{domxref("CSPViolationReport")}}, and {{domxref("PermissionsPolicyViolationReport")}}.
70-
These all have an origin `url`, a `type`, and a `body` that is specific to the report type.
71-
The type of report can be determined from its `type` property, which for the reports above would be `coep`, `deprecation`, `integrity-violation`, `intervention`, `csp-violation`, and `permissions-policy-violation`.
61+
Reports can also be sent to remote _server endpoints_ by the user agent in a `POST` operation with a {{HTTPHeader("Content-Type")}} of `application/reports+json`.
62+
They are serializations of the corresponding dictionary for each [report type](#report_types).
63+
For example, CSP violation reports are a serialization of a {{domxref("CSPViolationReport")}} object.
7264

73-
Reports sent to reporting endpoints and reporting observers are essentially the same.
74-
The only difference is that server reports are JSON serializations of the objects that have additional `user_agent` and `age` fields.
65+
Reports sent to endpoints can be retrieved independently of the running of the websites they relate to, which is useful — a crash for example could bring down a website and stop anything running, but a report could still be obtained to give the developer some clues as to why it happened.
7566

76-
A list of documented report types and their corresponding report dictionary are given in the [`options.types`](/en-US/docs/Web/API/ReportingObserver/ReportingObserver#types) parameter passed to the `ReportingObserver()` constructor.
67+
> [!NOTE]
68+
> There is no absolute guarantee of report delivery — a report could still fail to be collected if a serious error occurs.
69+
70+
The {{httpheader("Reporting-Endpoints")}} HTTP header is used to specify the name and URL for different endpoints that a user-agent has available to it for delivering reports.
71+
The endpoints can then be used on particular HTTP response headers to indicate the specific endpoint (or in some cases endpoints) that will be used for the associated report.
72+
Report types that don't have an associated HTTP header, such as `crash`, `deprecation`, and `intervention` reports, will usually send reports to the [`"default"` reporting endpoint](/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints#default_reporting_endpoint) (this is just an endpoint named "default" specified using the `Reporting-Endpoints` header).
73+
74+
The mechanism to specify server endpoint for each report is listed below.
75+
76+
- `coep`
77+
- `report-to` parameter on {{HTTPHeader("Cross-Origin-Embedder-Policy")}} or {{HTTPHeader("Cross-Origin-Embedder-Policy-Report-Only")}}
78+
- `csp-violation`
79+
- {{CSP("report-to")}} directive on {{HTTPHeader("Content-Security-Policy")}} or {{HTTPHeader("Content-Security-Policy-Report-Only")}}.
80+
- `integrity-violation`
81+
- [`endpoints`](/en-US/docs/Web/HTTP/Reference/Headers/Integrity-Policy#endpoints) field in {{httpheader("Integrity-Policy")}} or {{httpheader("Integrity-Policy-Report-Only")}}
82+
- `permissions-policy-violation`
83+
- `report-to` parameter on {{HTTPHeader("Permissions-Policy")}} or {{HTTPHeader("Permissions-Policy-Report-Only")}}
84+
- [`"default"` endpoint](/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints#default_reporting_endpoint)
85+
- `crash`
86+
- `crash-reporting` endpoint
87+
- `default` endpoint.
88+
- `deprecation`
89+
- `default` endpoint.
90+
- `intervention`
91+
- `default` endpoint.
7792

7893
### Generating reports via WebDriver
7994

@@ -117,18 +132,6 @@ These HTTP response headers define the endpoints where reports are sent.
117132
- {{HTTPHeader("Report-To")}} {{deprecated_inline}}
118133
- : No longer part of the Reporting API but still supported by some browsers. This sets the name and URL of reporting endpoint groups, which may be used with a number of HTTP headers especially for [Network Error Logging](/en-US/docs/Web/HTTP/Guides/Network_Error_Logging) that has not yet been updated to support `Reporting-Endpoints`. Other Reporting API reports should use `Reporting-Endpoints` instead for better future support.
119134

120-
Report endpoints can be set for the following reports using the {{CSP("report-to")}} directive or parameter on the corresponding headers:
121-
122-
- COEP violations
123-
- : {{HTTPHeader("Cross-Origin-Embedder-Policy")}} or {{HTTPHeader("Cross-Origin-Embedder-Policy-Report-Only")}}.
124-
- CSP violations
125-
- : {{HTTPHeader("Content-Security-Policy")}} or {{HTTPHeader("Content-Security-Policy-Report-Only")}}.
126-
127-
Report endpoints can be set for the following reports using the [`endpoints`](/en-US/docs/Web/HTTP/Reference/Headers/Integrity-Policy#endpoints) field in a structured dictionary on the corresponding headers:
128-
129-
- Integrity-Policy violations
130-
- : {{httpheader("Integrity-Policy")}} or {{httpheader("Integrity-Policy-Report-Only")}}.
131-
132135
## Examples
133136

134137
### Reporting deprecated features

0 commit comments

Comments
 (0)