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. There are a few ways to use it, which are detailed in the sections below.

Reporting server endpoints

Each unique origin you want to get reports for can be given a series of "endpoints", which are named URLs (or groups of URLs) that can be sent reports from a user agent. A reporting server at these endpoints can collect the reports, and process and present them as needed by your application.

The Reporting-Endpoints HTTP header is used to specify details about the different endpoints that a user-agent has available to it for delivering reports. The endpoints can then be used on particular HTTP response headers to indicate the specific endpoint (or in some cases endpoints) that will be used for the associated report. The directive or parameter used to specify an endpoint depends on the header. For example, the CSP report-to directive can be used on the Content-Security-Policy or Content-Security-Policy-Report-Only HTTP headers to specify the endpoint that CSP violation reports should be sent to, while the endpoints field is used on Integrity-Policy or Integrity-Policy-Report-Only to specify where to send integrity-policy violation reports.

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 reports themselves are sent to the target endpoint 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.

Reporting observers

Reports can also 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 retrieving the reports — but it is 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()).

Report types

Reports sent to reporting observers are instances of dictionary objects, such as COEPViolationReport, DeprecationReport, IntegrityViolationReport, InterventionReport, and CSPViolationReport. These all have an origin url, a type, and a body that is specific to the report type. The type of report can be determined from its type property, which for the reports above would be coep, deprecation, integrity-violation, intervention and csp-violation.

Reports sent to reporting endpoints and reporting observers 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.

A list of documented report types and their corresponding report dictionary are given in the options.types parameter passed to the ReportingObserver() constructor.

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

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.

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.

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.

Report endpoints can be set for the following reports using the report-to directive or parameter on the corresponding headers:

COEP violations

Cross-Origin-Embedder-Policy or Cross-Origin-Embedder-Policy-Report-Only.

CSP violations

Content-Security-Policy or Content-Security-Policy-Report-Only.

Report endpoints can be set for the following reports using the endpoints field in a structured dictionary on the corresponding headers:

Integrity-Policy violations

Integrity-Policy or Integrity-Policy-Report-Only.

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) => {
    //console.log(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