A new version of the Reporting API is available. It's more private and more likely to be supported across browsers.
The Reporting API informs you about errors that happen across your site as visitors use it. It gives you visibility on browser interventions, browser crashes, Content-Security-Policy violations, COOP/COEP violations, deprecation warnings and more.
A new version of the Reporting API is available. The new API is leaner and more likely to be supported across browsers.
Summary
Site developers
If you already have reporting functionality for your site: migrate to v1 by using the new header
(Reporting-Endpoints
), but keep the legacy header around for some time (Report-To
).
See Migration: example code.
If you're adding reporting functionality to your site just now: use only the new header
(Reporting-Endpoints
).
⚠️ In both cases, make sure to set the Reporting-Endpoints
header on all responses that might
generate reports.
Reporting service developers
If you're maintaining an endpoint service or are operating your own, expect more traffic as you
or external developers migrate to the Reporting API v1 (Reporting-Endpoints
header).
Keep reading for details and example code!
Network Error Logging
A new mechanism for Network Error Logging will be developed. Once that becomes available, switch from Reporting API v0 to that new mechanism.
Demo and code
- Demo site: new reporting API (v1)
- Code for the demo site
Differences between v0 and v1
What's changing
- The API surface is different.
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] } Document-Policy: ...; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default" Document-Policy: ...; report-to main-endpoint
- The scope of the report is different.
With v0, you can set reporting endpoints on some responses only. Other documents (pages) on that origin would automatically use these ambient endpoints.
With v1, you need to set the Reporting-Endpoints
header on all responses that might generate
reports.
- Both APIs support the same report types, with one exception: v1 does not support Network Error reports. Read more in the migration steps.
- v0 is not and will not be supported across browsers. v1 is more likely to be supported across multiple browsers in the future.
What remains unchanged
- The format and structure of the reports is unchanged.
- The request sent by the browser to the endpoint remains a
POST
request ofContent-type
application/reports+json
. - Mapping certain endpoints to certain report types is supported in both v0 and v1.
- The role of the
default
endpoint is unchanged. The Reporting API v1 has no impact on the
ReportingObserver
.ReportingObserver
continues getting access to all observable reports, and their format is identical.
All differences between v0 and v1
Legacy Reporting API (v0)Report-To header |
New Reporting API (v1)Reporting-Endpoints header |
|
---|---|---|
Browser support | Chrome 69+ and Edge 69+. | Chrome 96+ and Edge 96+. Firefox is supportive. Safari doesn't object. See browser signals. |
Endpoints | Sends reports to any of multiple report collectors (multiple URLs defined per endpoint group). | Sends reports to specific report collectors (only one URL defined per endpoint). |
API surface | Uses the `Report-To` header to configure named endpoint groups. |
Uses the `Reporting-Endpoints` header to configure named endpoints. |
Types of report that can be generated via this API |
|
Unchanged, except from Network Error Logging (NEL): this is not supported in the new Reporting API (v1). |
Report scope | Origin. A document's Report-To header affects other documents (pages) from that origin.
The url field of a report still varies per-document.
|
Document. A document's Reporting-Endpoints header only affects that document.
The url field of a report still varies per-document.
|
Report isolation (batching) | Different documents (pages) or sites/origins that generate a report around the same time and that have the same reporting endpoint will be batched together: they'll be sent in the same message to the reporting endpoint. |
|
Support for load balancing / priorities | Yes | No |
Endpoint developers: Expect more traffic
If you've set up your own server as a reporting endpoint, or if you're developing or maintaining a report collector as a service, expect more traffic to that endpoint.
This is because reports aren't batched with the Reporting API v1 as they are with the Reporting API v0. Therefore, as application developers start migrating to the Reporting API v1, the number of reports will remain similar, but the volume of requests to the endpoint server will increase.
Application developers: Migrate to Reporting-Endpoints
(v1)
What should you do?
Using the new Reporting API (v1) has several benefits ✅:
- Browser signals are positive, which means that cross-browser support can be expected for v1 (unlike v0 that is only supported in Chrome and Edge).
- The API is leaner.
- Tooling is being developed around the new Reporting API (v1).
With this in mind:
- If your site already uses the Reporting API v0 with the
Report-To
header, migrate to the Reporting API v1 (see the migration steps). If your site already uses reporting functionality for Content-Security-Policy violations, check the specific migration steps for CSP reporting. - If your site doesn't already use the Reporting API and you're now adding reporting functionality:
use the new Reporting API (v1) (the
Reporting-Endpoints
header). There's one exception to this: if you need to use Network Error Logging, useReport-To
(v0). Network Error Logging currently isn't supported in the Reporting API v1. A new mechanism for Network Error Logging will be developed⏤until that's available, use the Reporting API v0. If you need Network Error Logging alongside other report types, use bothReport-To
(v0) andReporting-Endpoints
(v1). v0 gives you Network Error Logging and v1 gives you reports of all other types.
Migration steps
Your goal in this migration is to not lose reports you used to get with v0.
Step 1 (do now): Use both headers:
Report-To
(v0) andReporting-Endpoints
(v1).With this, you get:
- Reports from newer Chrome and Edge clients thanks to
Reporting-Endpoints
(v1). - Reports from older Chrome and Edge clients thanks to
Report-To
(v0).
Browser instances that support
Reporting-Endpoints
will useReporting-Endpoints
, and instances that don't will fallback toReport-To
. The request and report format is the same for v0 and v1.- Reports from newer Chrome and Edge clients thanks to
Step 2 (do now): Ensure that the
Reporting-Endpoints
header is set on all responses that might generate reports.With v0, you could choose to set reporting endpoints on some responses only, and other documents (pages) on that origin would use this "ambient" endpoint. With v1, because of the difference in scoping, you need to set the
Reporting-Endpoints
header on all responses that might generate reports.Step 3 (start later): Once all or most of your users have updated to later Chrome or Edge installs (96 and later), remove
Report-To
(v0) and keep onlyReporting-Endpoints
.One exception: if you do need Network Error Logging reports, keep
Report-To
until a new mechanism is in place for Network Error Logging.
See code examples in the migration cookbook.
Migration steps for CSP reporting
There are two ways Content-Security-Policy violation reports can be configured:
- With the CSP header alone via the
report-uri
directive. This has wide browser support, across Chrome, Firefox, Safari and Edge. Reports are sent with the content-typeapplication/csp-report
and have a format that's specific to CSP. These reports are called "CSP Level 2 Reports" and do not rely on the Reporting API. - With the Reporting API, that is via
Report-To
header (legacy) or the newerReporting-Endpoints
(v1). This is supported in Chrome and Edge only. Report requests have the same format as other Reporting API requests, and the same content-typeapplication/reports+json
.
Using the first approach (only report-uri
) is no longer recommended and using the second approach has a few benefits. In particular, it enables you to using a single way to set up reporting for all report types as well as to set a generic endpoint (because all report requests generated via the Reporting API⏤CSP and others⏤have the same format application/reports+json
.
However, only a few browsers support report-to
.
Thus it's recommended that you keep report-uri
alongside the Reporting API approach (Report-To
or better, Reporting-Endpoints
) in order to get CSP violation reports from multiple browsers. In a
browser which recognizes report-uri
and report-to
, report-uri
will be ignored if report-to
is present. In a browser which recognizes only report-uri
, only report-uri
will be considered.
Step 1 (do now): If you haven't added it yet, add
report-to
alongsidereport-uri
. Browsers that support onlyreport-uri
(Firefox) will usereport-uri
, and browsers that also supportreport-to
(Chrome, Edge) will usereport-to
. To specify the named endpoints you'll use inreport-to
, use both headersReport-To
andReporting-Endpoints
. This ensures that you get reports from both older and newer Chrome and Edge clients.Step 3 (start later): Once all or most of your users have updated to later Chrome or Edge installs (96 and later), remove
Report-To
(v0) and keep onlyReporting-Endpoints
. Keepreport-uri
so you still get reports for browsers that only support it.
See code examples for these steps in CSP reporting migration.
Migration: example code
Overview
If you're using the legacy Reporting API (v0) to get violation reports for a a COOP
(Cross-Origin-Opener-Policy
header), a COEP (Cross-Origin-Embedder-Policy
) or a document policy
(Document-Policy
header): you do not need to change these policy headers themselves as you migrate
to Reporting API v1. What you do need is to migrate from the legacy Report-To
header to the new
Reporting-Endpoints
header.
If you're using the legacy Reporting API (v0) to get violation reports for a CSP
(Content-Security-Policy
header), you may need to tweak your Content-Security-Policy
as part of
your migration to the new Reporting API (v1).
Basic migration
Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default" Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Note that with v1, you can still send specific report types to specific endpoints. But you can have only one URL per endpoint.
Observing all pages
app.get("/", (request, response) => { response.set("Report-To", …) response.render(...) }); app.get("/page1", (request, response) => { response.render(...) });
// Use a middleware to set the reporting endpoint(s) for *all* requests. app.use(function(request, response, next) { response.set("Reporting-Endpoints", …); next(); }); app.get("/", (request, response) => { response.render(...) }); app.get("/page1", (request, response) => { response.render(...) });
CSP reporting migration
Content-Security-Policy: ...; report-uri https://reports.example/main
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Report-To: main-endpoint="https://reports.example/main"
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Reporting-Endpoints: main-endpoint="https://reports.example/main" Report-To: ...
Further reading
- Monitor your web application with the Reporting API (main post on the Reporting API)
- Specification: legacy Reporting API (v0)
- Specification: new Reporting API (v1)
Hero image by Nine Koepfer / @enka80 on Unsplash, edited. With many thanks to Ian Clelland, Eiji Kitamura and Milica Mihajlija for their reviews and suggestions on this article.