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.

Maud Nalpas

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.

• 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 of Content-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

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, use Report-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 both Report-To (v0) and Reporting-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.

1. Step 1 (do now): Use both headers: Report-To (v0) and Reporting-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.

2. 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.

3. 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 only Reporting-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-type application/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 newer Reporting-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-type application/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.

1. Step 1 (do now): If you haven't added it yet, add report-to alongside report-uri. Browsers that support only report-uri (Firefox) will use report-uri, and browsers that also support report-to(Chrome, Edge) will use report-to. To specify the named endpoints you'll use in report-to, use both headers Report-To and Reporting-Endpoints. This ensures that you get reports from both older and newer Chrome and Edge clients.

2. 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 only Reporting-Endpoints. Keep report-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.