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

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

{0 uses the Report-To header to configure named endpoint groups, and the report-to directive in other headers to reference these endpoint groups.

v1 (new)
 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

v1 uses the Reporting-Endpoints header to configure named endpoints. Like v0, it uses the report-to directive in other headers to reference these endpoint groups.

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

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
  • Deprecation
  • Intervention
  • Crash
  • COOP/COEP
  • Content-Security-Policy Level 3 (CSP Level 3)
  • Network Error Logging (NEL)
Learn more about the report types in the Reporting API post.
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.
  • Reports from different documents (pages) are never sent together. Even if two documents (pages) from the same origin generate a report at the same time, for the same endpoint, these won't be batched. This is a mechanism to mitigate privacy attacks.
  • Reports from the same document (page) may be sent together.
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, 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

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" }] }

If you already have reporting functionality in your site, keep Report-To only temporarily (until most Chrome and Edge clients have been updated) to avoid losing reports.

If you need Network Error Logging, keep Report-To until Network Error Logging replacement becomes available.

New code (with v1 only)
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

This is what your code can look like in the future, once most Chrome and Edge clients have been updated and support the API v1.

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(...)
});

With v0, you can set reporting endpoints on some responses only. Other documents (pages) on that origin automatically use these ambient endpoints. Here, the endpoints set for "/" are used for all responses, for example for page1.

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(...)
});

With v1, you need to set the Reporting-Endpoints header on all responses that might generate reports.

CSP reporting migration

Legacy code, with report-uri only
Content-Security-Policy: ...; report-uri https://reports.example/main

Using only report-uri is no longer recommended. If your code looks like above, migrate. See the New code examples below (in green).

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"

This is better: this code uses report-to, the newer replacement to report-uri. It still keeps report-uri around for backwards compatibility; several browsers don't support report-to but do support report-uri.

Still, this could be better: this codes uses the Reporting API v0 (Report-To header). Migrate to v1: see the 'New code' examples below (in green).

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

Keep the report-uri directive alongide the report-to directive until the report-to directive is supported across browsers. See the browser compatibility table.

Keep Report-To alongside Reporting-Endpoints temporarily. Once most of your Chrome and Edge visitors have upgraded to 96+ browser versions, remove Report-To.

Further reading

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.