Intervention Reporting

1. Introduction

[INTRODUCTION GOES HERE]

1.1. Examples

Example, Inc. wants to understand how often users of its web site are running into browser interventions, in order to better devote its developer resources to improving site performance. It can do this by delivering the following header to define a default reporting endpoint, which will direct intervention reports there:

Reporting-Endpoints: default="https://example.com/reports"

2. Concepts

2.1. Intervention

Interventions are discussed in https://github.com/WICG/interventions.

3. Intervention Reports

Intervention reports indicate that a user agent has decided not to honor a request made by the application (e.g. for security, performance or user annoyance reasons).

Intervention reports are a type of report.

Intervention reports have the report type "intervention".

Intervention reports are visible to ReportingObservers.

[Exposed=(Window,Worker)]
interface InterventionReportBody : ReportBody {
  [Default] object toJSON();
  readonly attribute DOMString id;
  readonly attribute DOMString message;
  readonly attribute DOMString? sourceFile;
  readonly attribute unsigned long? lineNumber;
  readonly attribute unsigned long? columnNumber;
};

An intervention report’s body, represented in JavaScript by InterventionReportBody, contains the following fields:

id: an implementation-defined string identifying the specific intervention that occurred. This string can be used for grouping and counting related reports.
message: A human-readable string with details typically matching what would be displayed on the developer console. The message is not guaranteed to be unique for a given id (e.g. it may contain additional context on what led to the intervention).
sourceFile: If known, the file which first used the indicated API, or null otherwise.
lineNumber: If known, the line number in sourceFile of the offending behavior (which prompted the intervention), or null otherwise.
columnNumber: If known, the column number in sourceFile of the offending behavior (which prompted the intervention), or null otherwise.

Note: Intervention reports are always delivered to the endpoint named default; there is currently no way to override this. If you want to receive other kinds of reports, but not intervention reports, make sure to use a different name for the endpoint that you choose for those reports.

4. Sample Reports

    POST /reports HTTP/1.1
    Host: example.com
    ...
    Content-Type: application/reports+json

    [{
      "type": "intervention",
      "age": 27,
      "url": "https://example.com/",
      "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
      "body": {
        "id": "audio-no-gesture",
        "message": "A request to play audio was blocked because it was not triggered by user activation (such as a click).",
        "sourceFile": "https://example.com/index.js",
        "lineNumber": 1234,
        "columnNumber": 42
      }
    }]
}

5. Security Considerations

For a discussion of security considerations surrounding out-of-band reporting in general, see Reporting API §9 Security Considerations.

The remainder of this section discusses security considerations for intervention reporting specifically.

6. Privacy Considerations

For a discussion of privacy considerations surrounding out-of-band reporting in general, see Reporting API §10 Privacy Considerations.

The remainder of this section discusses privacy considerations for intervention reporting specifically.