The Reporting API provides a generic reporting mechanism for web applications to use to make reports available based on various platform features (for exampleContent Security Policy,Permissions-Policy, or feature deprecation reports) in a consistent manner.

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

TheReporting-Endpoints HTTP header is used to specify details about the different endpoints that a user-agent has available to it for delivering reports.Thereport-to directive can then be used on particular HTTP response headers to indicate the specific endpoint that will be used for the associated report.For example, the CSPreport-to directive can be used on theContent-Security-Policy orContent-Security-Policy-Report-Only HTTP headers to specify the endpoint that CSP violation reports should be sent to.

The reports themselves are sent to the target endpoint by the user agent in aPOST operation with aContent-Type ofapplication/reports+json.They are serializations ofReport objects, where thetype indicates the type of report, theurl indicates the origin of the report, and thebody contains a serialization of the API interface that corresponds to the report type.For example, CSP violation reports have atype ofcsp-violation and abody that is a serialization of aCSPViolationReportBody 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 viaReportingObserver 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.

AReportingObserver object is created using theReportingObserver() 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 sameReportingObserver 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 type 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 endpoints and reporting observers are essentially the same: they have an originurl, atype, and abody that is an instance of the interface corresponding with that type.The only difference is that server reports are JSON serializations of the objects.

The mapping of reporttype tobody is shown below.

Generating reports via WebDriver

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

Interfaces

DeprecationReportBody

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

InterventionReportBody

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.

Report

An object representing a single report.

ReportingObserver

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

Related interfaces

These interfaces are defined as part of the HTTPContent Security Policy (CSP) specifications:

CSPViolationReportBody

Contains details of a CSP violation.

SecurityPolicyViolationEvent

Represents the event object of asecuritypolicyviolation event fired on an element, document, or worker when its CSP is violated.

This interface is defined as part of theSubresource Integrity specification:

IntegrityViolationReportBody

Contains information about a resource that was blocked because it did not meet the Subresource Integrity guarantees required by itsIntegrity-Policy, or that would be blocked for report-only policies set usingIntegrity-Policy-Report-Only.

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 thereport-to directive, which may be used with a number of HTTP headers includingContent-Security-Policy and orContent-Security-Policy-Report-Only.

Report-ToDeprecated

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

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

CSP violations

Content-Security-Policy orContent-Security-Policy-Report-Only.

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

Integrity-Policy violations

Integrity-Policy orIntegrity-Policy-Report-Only.

Examples

Reporting deprecated features

In ourdeprecation_report.html example, we create a simple reporting observer to observe usage of deprecated features on our web page:

const options = {  types: ["deprecation"],  buffered: true,};const observer = new ReportingObserver((reports, observer) => {  reportBtn.onclick = () => displayReports(reports);}, options);

We then tell it to start observing reports usingReportingObserver.observe(); this tells the observer to start collecting reports in its report queue, and runs the callback function specified inside the constructor:

observer.observe();

Later on in the example we deliberately use the deprecated version ofMediaDevices.getUserMedia():

if (navigator.mozGetUserMedia) {  navigator.mozGetUserMedia(constraints, success, failure);} else {  navigator.getUserMedia(constraints, success, failure);}

This causes a deprecation report to be generated; because of the event handler we set up inside theReportingObserver() constructor, we can now click the button to display the report details.

Specifications

Browser compatibility

See also

• Content Security Policy
• Permissions-Policy