index.bs

<h1>Intervention Reporting</h1>
<pre class="metadata">
Status: w3c/CG-DRAFT
ED: https://wicg.github.io/intervention-reporting/
Shortname: intervention-reporting
Group: WICG
Editor: Ian Clelland 76841, Google Inc., iclelland@google.com
Abstract:
  This document defines mechanism for reporting user agent interventions to site
  owners through the use of the Reporting API.
Level: 1
Indent: 2
Version History: https://github.com/WICG/intervention-reporting/commits/gh-pages
Boilerplate: omit conformance, omit feedback-header
!Participate: <a href="https://github.com/WICG/intervention-reporting/issues/new">File an issue</a> (<a href="https://github.com/WICG/intervention-reporting/issues">open issues</a>)
Markup Shorthands: css off, markdown on
</pre>
<section>
  <h2 id="intro">Introduction</h2>

  [INTRODUCTION GOES HERE]

  <h3 id="examples">Examples</h3>

  <div class="example">
    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:

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

</section>

<section>
  <h2 id="concept">Concepts</h2>

  <h3 id="concept-intervention">Intervention</h3>

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

</section>

<section>
  <h2 id="intervention-report">Intervention Reports</h3>

  <dfn>Intervention reports</dfn> 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).

  <a>Intervention reports</a> are a type of [=report=].

  <a>Intervention reports</a> have the <a>report type</a> "intervention".

  <a>Intervention reports</a> are <a>visible to
  <code>ReportingObserver</code>s</a>.

  <pre class="idl">
    [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;
    };
  </pre>

  An <a>intervention report</a>'s [=report/body=], represented in JavaScript by
  {{InterventionReportBody}}, contains the following fields:

    - <dfn for="InterventionReportBody">id</dfn>: an implementation-defined
      string identifying the specific intervention that occurred. This string
      can be used for grouping and counting related reports.

    - <dfn for="InterventionReportBody">message</dfn>: 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
      [=InterventionReportBody/id=] (e.g. it may contain additional context on
      what led to the intervention).

    - <dfn for="InterventionReportBody">sourceFile</dfn>: If known, the file
      which first used the indicated API, or null otherwise.

    - <dfn for="InterventionReportBody">lineNumber</dfn>: If known, the line
      number in [=InterventionReportBody/sourceFile=] of the offending behavior
      (which prompted the intervention), or null otherwise.

    - <dfn for="InterventionReportBody">columnNumber</dfn>: If known, the
      column number in [=InterventionReportBody/sourceFile=] of the offending
      behavior (which prompted the intervention), or null otherwise.


  Note: Intervention reports are always delivered to the <a>endpoint</a> named
  <code>default</code>; 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.
</section>

<section>
  <h2 id="sample-reports">Sample Reports</h2>

  <div class="example">
  <pre>
      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
        }
      }]
  }
  </pre>
  </div>
</section>

<section>
  <h2 id="security">Security Considerations</h2>

  For a discussion of security considerations surrounding out-of-band reporting
  in general, see [[REPORTING#security]].

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

<section>
  <h2 id="privacy">Privacy Considerations</h2>

  For a discussion of privacy considerations surrounding out-of-band reporting
  in general, see [[REPORTING#privacy]].

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