Intervention Reporting

Editor’s Draft,

This version:
https://wicg.github.io/intervention-reporting/
Version History:
https://github.com/WICG/intervention-reporting/commits/gh-pages
Editor:
(Google Inc.)
Participate:
File an issue (open issues)

Abstract

This document defines mechanism for reporting user agent interventions to site owners through the use of the Reporting API.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

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 reporting endpoint, and direct intervention reports to it:
Report-To: { "group": "default",
             "max_age": 10886400,
             "endpoints": [
               { "url": "https://example.com/reports", "priority": 1 },
               { "url": "https://backup.com/reports", "priority": 2 }
             ] }

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:

Note: Intervention reports are always delivered to the endpoint group 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 group 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 §security.

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 §privacy.

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

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[REPORTING-1]
Douglas Creager; et al. Reporting API. 25 September 2018. WD. URL: https://www.w3.org/TR/reporting-1/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

[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;
};