Migrate to Reporting API v1
A new version of the Reporting API is available. It's more private and more likely to be supported across browsers.
This post covers how to migrate to the new version of the Reporting API (v1). If you're new to the Reporting API or need detailed usage examples, head over to the main post on the Reporting API instead.
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.
The legacy Reporting API is named Reporting API v0. The new Reporting API is named Reporting API v1.
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
If you use Network Error Logging, continue using Report-To
(v0) because Network Error Logging isn't supported in the Reporting API v1.
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.
v0 (legacy)
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
v1 (new)
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.
v0 (legacy)
With v0, you can set reporting endpoints on some responses only. Other documents (pages) on that origin would automatically use these ambient endpoints.
v1 (new)
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
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.
Reporting-Endpoints
(v1)
Application developers: Migrate to 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.
Because only Chrome and Edge support the Reporting API v0, you don't need to focus on other browsers during your migration to v1. However, keep in mind that broader browser support may be coming. There are no tracking bugs for these browsers at the moment but this may change.
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 use Reporting-Endpoints
, and instances that don't will fallback to Report-To
. The request and report format is the same for v0 and v1.
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
Legacy code (with v0)
Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }
New code (transition code with v0 alongside v1)
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" }] }
New code (with v1 only)
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
Legacy code (with v0), for example with Express
app.get("/", (request, response) => {
response.set("Report-To", …)
response.render(...)
});
app.get("/page1", (request, response) => {
response.render(...)
});
New code (with v1), for example with Express
// 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
Legacy code, with report-uri only
Content-Security-Policy: ...; report-uri https://reports.example/main
Better legacy code, with report-uri and the report-to directive with the Report-To (v0) header
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"
New code, with report-uri and the report-to directive with the Reporting-Endpoints (v1) header
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.