Reporting API

Concepts and usage

There are several different features and problems on the web platform that generate information useful to web developers when they are trying to fix bugs or improve their websites in other ways. Such information can include:

• Content Security Policy violations.
• Permissions-Policy violations.
• Integrity-Policy violations.
• Cross-Origin-Embedder-Policy violations.
• Deprecated feature usage (when you are using something that will stop working soon in browsers).
• Occurrence of crashes.
• 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).

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.

Reports can be retrieved via JavaScript reporting observers or sent to a remote server endpoint. The types of reports and the two reporting approaches are detailed in the sections below.

Report types

Reports sent to reporting observers are instances of dictionary objects. These all have type, url, and body properties, where the type indicates the type of report, and the body is specific to the report type.

Reports sent to reporting endpoints are essentially the same. The only difference is that server reports are JSON serializations of the objects that have additional user_agent and age fields.

The following table lists the documented report types, their corresponding report dictionaries, and notes on the violation. Note that, except for crash reports, which can't be observed in JavaScript (because the observing page has crashed), all the listed reports are visible in observers and can be sent to server endpoints.

A list of the types is also is given in the options.types parameter passed to the ReportingObserver() constructor.

Reporting observers

Reports can be obtained via ReportingObserver objects created via JavaScript inside the website you are aiming to get reports on. This method is not as failsafe as sending reports to the server because any page crash could stop you from retrieving the reports; it is, however, easier to set up, and more flexible.

A ReportingObserver object is created using the ReportingObserver() constructor, which is passed two parameters:

• A callback function with two parameters — an array of the reports available in the observer's report queue and a copy of the same ReportingObserver object, which allows observation to be controlled directly from inside the callback. The callback runs when observation starts.
• An options dictionary that allows you to specify the types of reports to collect, and whether reports generated before the observer was created should be observable (buffered: true).

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

Reporting server endpoints

Reports can also be sent to remote server endpoints by the user agent in a POST operation with a Content-Type of application/reports+json. They are serializations of the corresponding dictionary for each report type. For example, CSP violation reports are a serialization of a CSPViolationReport object.

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.

The 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. The endpoints can then be specified within particular HTTP response headers to indicate the endpoint (or in some cases, endpoints) that associated reports will be delivered to. 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 (this is just an endpoint named "default" specified using the Reporting-Endpoints header).

The mechanisms to specify server endpoints for each report type are listed below:

coep

• report-to parameter on Cross-Origin-Embedder-Policy or Cross-Origin-Embedder-Policy-Report-Only

csp-violation

• report-to directive on Content-Security-Policy or Content-Security-Policy-Report-Only.

integrity-violation

• endpoints field in Integrity-Policy or Integrity-Policy-Report-Only

permissions-policy-violation

• report-to parameter on Permissions-Policy or Permissions-Policy-Report-Only
• "default" endpoint

crash

• crash-reporting endpoint
• default endpoint.

deprecation

• default endpoint.

intervention

• default endpoint.

Generating reports via WebDriver

The Reporting API spec also defines a Generate Test Report WebDriver extension, which allows you to simulate report generation during automation. Reports generated via WebDriver are observed by any registered ReportingObserver objects present in the loaded website. This is not yet documented.

Interfaces

CrashReportContext

Provides methods enabling arbitrary data to be recorded for the current top-level browsing context, which is then added to a CrashReport and sent to a reporting endpoint when a browser crash occurs.

ReportingObserver

An object that can be used to collect and access reports as they are generated.

Related interfaces

SecurityPolicyViolationEvent

Represents the event object of a securitypolicyviolation event fired on an element, document, or worker when its CSP is violated. This is defined as part of the HTTP Content Security Policy (CSP) specifications.

Dictionaries

COEPViolationReport

Contains details of a Cross-Origin-Embedder-Policy (COEP) violation.

CrashReport

Contains details of a browser crash.

CSPViolationReport

Contains details of a CSP violation. This is defined as part of the HTTP Content Security Policy (CSP) specifications.

DeprecationReport

Contains details of deprecated web platform features that a website is using.

InterventionReport

Contains details of an intervention report, which is generated when a request made by the website has been denied by the browser; e.g., for security reasons.

IntegrityViolationReport

Contains information about a resource that was blocked because it did not meet the Subresource Integrity guarantees required by its Integrity-Policy, or that would be blocked for report-only policies set using Integrity-Policy-Report-Only. This is defined as part of the Subresource Integrity specification.

PermissionsPolicyViolationReport

Contains details of a Permissions-Policy violation.

Related HTTP Headers

These HTTP response headers define the endpoints where reports are sent.

Reporting-Endpoints

Sets the name and URL of reporting endpoints. These endpoints can be used in the report-to directive, which may be used with a number of HTTP headers including Content-Security-Policy or Content-Security-Policy-Report-Only.

Report-To Deprecated

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 that has not yet been updated to support Reporting-Endpoints. Other Reporting API reports should use Reporting-Endpoints instead for better future support.

Examples

Reporting deprecated features

This example shows how to observe "deprecation" reports within a page that triggers them using a ReportingObserver.

Note we've chosen to display a "deprecation" report because it doesn't require that particular HTTP headers are set, and can therefore be run as an MDN live example.

<pre id="log"></pre>

#log {
  height: 200px;
  margin: 10px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

JavaScript

First we construct a new ReportingObserver object to listen for reports with the type "deprecation", passing a callback that will receive and log the reports.

const options = {
  types: ["deprecation"],
  buffered: true,
};

const observer = new ReportingObserver((reports, observer) => {
  reports.forEach((report) => {
    log(JSON.stringify(report, null, 2));
  });
}, options);

// Start the observer
observer.observe();

We then call the following code which uses synchronous XHR (deprecated API). Note that this is defined after the observer it triggers once the observer is running.

const xhr = new XMLHttpRequest();
xhr.open("GET", "/", false); // false = synchronous (deprecated)
xhr.send();

Results

On browsers that support deprecation reports, a report should be displayed below. Note that the type is "deprecation".

Specifications

Browser compatibility

See also

• Content Security Policy
• Permissions-Policy