Permissions-Policy-Report-Only and Reporting API updates

files/en-us/web/api/crashreport/index.md

@@ -30,7 +30,7 @@ The `CrashReport` dictionary of the [Reporting API](/en-US/docs/Web/API/Reportin
     - `is_top_level` {{experimental_inline}}
       - : A boolean indicating whether the crashed document was a top-level document (`true`) or an embedded document (`false`).
     - `reason` {{experimental_inline}} {{optional_inline}}
-      - : A string indicating the specfic reason why the crash occurred, if known. Possible values are:
+      - : A string indicating the specific reason why the crash occurred, if known. Possible values are:
         - `oom`
           - : The page ran out of memory.
         - `unresponsive`

files/en-us/web/api/crashreportcontext/index.md

@@ -69,7 +69,7 @@ async function fetchURL(url) {
 }
 ```
 
-This also prevents key-value pairs that identify the same issue occuring at different times or places from overwriting one another. In this case, we differentiate crash report data set in the top-level document versus data set in embeded documents.
+This also prevents key-value pairs that identify the same issue occuring at different times or places from overwriting one another. In this case, we differentiate crash report data set in the top-level document versus data set in embedded documents.
 
 ## Specifications
 

files/en-us/web/api/permissionspolicyviolationreport/index.md

@@ -11,7 +11,7 @@ browser-compat: api.ReportingObserver.ReportingObserver.options_parameter.types_
 
 The `PermissionsPolicyViolationReport` dictionary of the [Reporting API](/en-US/docs/Web/API/Reporting_API) represents a report that is generated when a document violates its [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy).
 
-Reports of this type can be observed from within a page using a {{domxref("ReportingObserver")}}, and a serialized version can be sent to the [default reporting server endpoint](/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints#default_reporting_endpoint).
+Reports of this type can be observed from within a page using a {{domxref("ReportingObserver")}}, and a serialized version can be sent to a reporting server endpoint.
 
 ## Instance properties
 
@@ -47,15 +47,16 @@ Reports of this type can be observed from within a page using a {{domxref("Repor
 
 Permissions Policy violations are reported when a document attempts to use a browser feature that is blocked by its [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy).
 The policy is set using the {{httpheader("Permissions-Policy")}} HTTP header, or a `<meta http-equiv="permissions-policy">` element.
+Violations of the policy may also be reported but not enforced using the {{httpheader("Permissions-Policy-Report-Only")}} HTTP header, or a `<meta http-equiv="permissions-policy-report-only">` element.
 
 You can monitor for Permissions-Policy violation reports within the page that sets the policy using the [Reporting API](/en-US/docs/Web/API/Reporting_API).
 To do this you create a {{domxref("ReportingObserver")}} object to listen for reports, passing a callback method and an (optional) `options` property specifying the types of reports that you want to report on.
 The callback method is then called with reports of the requested types, passing a report object.
-For `Permissions-Policy` violations, the object will be a `PermissionsPolicyViolationReport` instance with `PermissionsPolicyViolationReport.type == "permissions-policy-violation"`.
+For `Permissions-Policy` or `Permissions-Policy-Report-Only` violations, the object will be a `PermissionsPolicyViolationReport` instance with `PermissionsPolicyViolationReport.type === "permissions-policy-violation"`.
 
 The structure of a typical in-page report is shown below.
 Note that we can see the URL of the page that had its policy violated (`url`), and from `body.featureId` we can see which feature was blocked.
-The `body.disposition` field shows that the violation was enforced.
+The `body.disposition` field shows that the violation was enforced or only reported.
 
 ```json
 {
@@ -66,14 +67,14 @@ The `body.disposition` field shows that the violation was enforced.
     "lineNumber": 44,
     "columnNumber": 29,
     "featureId": "geolocation",
-    "disposition": "enforce",
+    "disposition": "enforce", // Policy was enforced!
     "message": "Permissions policy violation: geolocation access has been blocked because of a permissions policy applied to the current document."
   }
 }
 ```
 
-Violation reports may also be sent as a JSON object in a {{httpmethod("POST")}} request to the [reporting server endpoint](/en-US/docs/Web/API/Reporting_API#reporting_server_endpoints) named `"default"`, if one is defined.
-The reporting server endpoint and its mapping to a particular URL are set using the {{httpheader("Reporting-Endpoints")}} header.
+Violation reports may also be sent as a JSON object in a {{httpmethod("POST")}} request to the [reporting server endpoint](/en-US/docs/Web/API/Reporting_API#reporting_server_endpoints) indicated by name in a per-directive `report-to` parameter, with fallback to the [`default` reporting server endpoint](/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints#default_reporting_endpoint) (if defined).
+The reporting server endpoint and its mapping to a particular URL are set using the {{httpheader("Reporting-Endpoints")}} response header.
 
 The structure of the server report is almost exactly the same as `PermissionsPolicyViolationReport`, except that it additionally includes `age` and `user_agent` fields.
 
@@ -163,13 +164,24 @@ Note that the `type` is `"permissions-policy-violation"` and `body.featureId` id
 
 ### Sending a Permissions Policy violation report to a reporting endpoint
 
-Here we define the define reporting endpoint named `"default"` using the {{httpheader("Reporting-Endpoints")}} response header, and set the `Permissions-Policy` header to block use of the `geolocation` feature.
+This example shows how to configure reporting of `Permissions-Policy` violations to a server endpoint.
+
+The response headers below block geolocation and define the reporting endpoint name for the feature as "geo_endpoint".
+The {{HTTPHeader("Reporting-Endpoints")}} HTTP response header is used to define the URL of this endpoint name.
 
 ```http
-Reporting-Endpoints: default="https://example.com/reports"
-Permissions-Policy: geolocation=()
+Reporting-Endpoints: geo_endpoint="https://example.com/reports"
+Permissions-Policy: geolocation=();report-to=geo_endpoint
 ```
 
+> [!NOTE]
+> To send all violation reports to the same endpoint we might instead define the [`"default"` reporting endpoint](/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints#default_reporting_endpoint):
+>
+> ```http
+> Reporting-Endpoints: default="https://example.com/reports"
+> Permissions-Policy: geolocation=()
+> ```
+
 As before, a violation is triggered by attempting to use a blocked feature:
 
 ```js
@@ -214,6 +226,7 @@ Note that the `type` is `"permissions-policy-violation"` and the `body` property
 
 - {{domxref("ReportingObserver")}}
 - {{httpheader("Permissions-Policy")}}
+- {{httpheader("Permissions-Policy-Report-Only")}}
 - {{httpheader("Reporting-Endpoints")}}
 - [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy)
 - [Reporting API](/en-US/docs/Web/API/Reporting_API)

files/en-us/web/api/reporting_api/index.md

@@ -29,34 +29,39 @@ There are several different features and problems on the web platform that gener
 - 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.
+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.
 
-### Reporting server endpoints
+Reports can be retrieved via JavaScript reporting observers or sent to a remote server endpoint.
+The types of reports and the two reporting approaches are detailed in the sections below.
 
-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.
+### Report types
 
-The {{httpheader("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 {{CSP("report-to")}} directive can be used on the {{HTTPHeader("Content-Security-Policy")}} or {{HTTPHeader("Content-Security-Policy-Report-Only")}} HTTP headers to specify the endpoint that CSP violation reports should be sent to, while the [`endpoints`](/en-US/docs/Web/HTTP/Reference/Headers/Integrity-Policy#endpoints) field is used on {{httpheader("Integrity-Policy")}} or {{httpheader("Integrity-Policy-Report-Only")}} to specify where to send integrity-policy violation reports.
+Reports sent to reporting observers are instances of dictionary objects.
+These all have `type`, `url`, and `body` properties, where the `type` indicates the type of report, and the `body` is specific to the report type.
 
-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.
+Reports sent to reporting endpoints 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.
 
-> [!NOTE]
-> There is no absolute guarantee of report delivery — a report could still fail to be collected if a serious error occurs.
+The following table lists the documented report types, their corresponding report dictionaries, and notes on the violation.
+Note that except for `crash` reports, which can't be observed in JavaScript (because the observing page has crashed), all the listed reports are visible in both observers and can be sent to server endpoints.
 
-The reports themselves are sent to the target endpoint by the user agent in a `POST` operation with a {{HTTPHeader("Content-Type")}} of `application/reports+json`.
-They are serializations of the corresponding dictionary for each [report type](#report_types).
-For example, CSP violation reports are a serialization of a {{domxref("CSPViolationReport")}} object.
+| Type                           | Report object                                   | Notes                                                                                      |
+| ------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `coep`                         | {{domxref("COEPViolationReport")}}              | {{httpheader("Cross-Origin-Embedder-Policy")}} (COEP) violations                           |
+| `coop`                         | `COOPViolationReport`                           | {{httpheader("Cross-Origin-Opener-Policy")}} (COOP) violations                             |
+| `crash`                        | {{domxref("CrashReport")}}                      | Browser crash reports                                                                      |
+| `csp-violation`                | {{domxref("CSPViolationReport")}}               | [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violations                |
+| `deprecation`                  | {{domxref("DeprecationReport")}}                | Deprecated features used by the site.                                                      |
+| `integrity-violation`          | {{domxref("IntegrityViolationReport")}}         | {{httpheader("Integrity-Policy")}} violations                                              |
+| `intervention`                 | {{domxref("InterventionReport")}}               | Features blocked by the user agent, such as ads that significantly impact page performance |
+| `permissions-policy-violation` | {{domxref("PermissionsPolicyViolationReport")}} | {{httpheader("Permissions-Policy")}} violations                                            |
 
-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.
+A list of the types is also is given in the [`options.types`](/en-US/docs/Web/API/ReportingObserver/ReportingObserver#types) parameter passed to the `ReportingObserver()` constructor.
 
 ### Reporting observers
 
-Reports can also be obtained via {{domxref("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.
+Reports can be obtained via {{domxref("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 from retrieving the reports; it is, however, easier to set up, and more flexible.
 
 A `ReportingObserver` object is created using the {{domxref("ReportingObserver.ReportingObserver", "ReportingObserver()")}} constructor, which is passed two parameters:
 
@@ -65,16 +70,52 @@ A `ReportingObserver` object is created using the {{domxref("ReportingObserver.R
 
 Methods are then available on the observer to start collecting reports ({{domxref("ReportingObserver.observe()")}}), retrieve the reports currently in the report queue ({{domxref("ReportingObserver.takeRecords()")}}), and disconnect the observer so it can no longer collect records ({{domxref("ReportingObserver.disconnect()")}}).
 
-### Report types
+### Reporting server endpoints
 
-Reports sent to reporting observers are instances of dictionary objects, such as {{domxref("COEPViolationReport")}}, {{domxref("CrashReport")}}, {{domxref("DeprecationReport")}}, {{domxref("IntegrityViolationReport")}}, {{domxref("InterventionReport")}}, {{domxref("CSPViolationReport")}}, and {{domxref("PermissionsPolicyViolationReport")}}.
-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`, `crash`, `deprecation`, `integrity-violation`, `intervention`, `csp-violation`, and `permissions-policy-violation`.
+Reports can also be sent to remote _server endpoints_ by the user agent in a `POST` operation with a {{HTTPHeader("Content-Type")}} of `application/reports+json`.
+They are serializations of the corresponding dictionary for each [report type](#report_types).
+For example, CSP violation reports are a serialization of a {{domxref("CSPViolationReport")}} object.
 
-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.
+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.
+
+> [!NOTE]
+> There is no absolute guarantee of report delivery — a report could still fail to be collected if a serious error occurs.
+
+The {{httpheader("Reporting-Endpoints")}} HTTP header is used to specify the name and URL for different endpoints that a user-agent has available to it for delivering reports.
+The endpoints can then be specified within particular HTTP response headers to indicate the endpoint (or in some cases, endpoints) that associated reports will be delivered to.
+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](/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints#default_reporting_endpoint) (this is just an endpoint named "default" specified using the `Reporting-Endpoints` header).
 
-A list of documented report types and their corresponding report dictionary are given in the [`options.types`](/en-US/docs/Web/API/ReportingObserver/ReportingObserver#types) parameter passed to the `ReportingObserver()` constructor.
+The mechanisms to specify server endpoints for each report type are listed below:
+
+`coep`
+
+- `report-to` parameter on {{HTTPHeader("Cross-Origin-Embedder-Policy")}} or {{HTTPHeader("Cross-Origin-Embedder-Policy-Report-Only")}}
+
+`csp-violation`
+
+- {{CSP("report-to")}} directive on {{HTTPHeader("Content-Security-Policy")}} or {{HTTPHeader("Content-Security-Policy-Report-Only")}}.
+
+`integrity-violation`
+
+- [`endpoints`](/en-US/docs/Web/HTTP/Reference/Headers/Integrity-Policy#endpoints) field in {{httpheader("Integrity-Policy")}} or {{httpheader("Integrity-Policy-Report-Only")}}
+
+`permissions-policy-violation`
+
+- `report-to` parameter on {{HTTPHeader("Permissions-Policy")}} or {{HTTPHeader("Permissions-Policy-Report-Only")}}
+- [`"default"` endpoint](/en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints#default_reporting_endpoint)
+
+`crash`
+
+- `crash-reporting` endpoint
+- `default` endpoint.
+
+`deprecation`
+
+- `default` endpoint.
+
+`intervention`
+
+- `default` endpoint.
 
 ### Generating reports via WebDriver
 
@@ -122,18 +163,6 @@ These HTTP response headers define the endpoints where reports are sent.
 - {{HTTPHeader("Report-To")}} {{deprecated_inline}}
   - : 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](/en-US/docs/Web/HTTP/Guides/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 {{CSP("report-to")}} directive or parameter on the corresponding headers:
-
-- COEP violations
-  - : {{HTTPHeader("Cross-Origin-Embedder-Policy")}} or {{HTTPHeader("Cross-Origin-Embedder-Policy-Report-Only")}}.
-- CSP violations
-  - : {{HTTPHeader("Content-Security-Policy")}} or {{HTTPHeader("Content-Security-Policy-Report-Only")}}.
-
-Report endpoints can be set for the following reports using the [`endpoints`](/en-US/docs/Web/HTTP/Reference/Headers/Integrity-Policy#endpoints) field in a structured dictionary on the corresponding headers:
-
-- Integrity-Policy violations
-  - : {{httpheader("Integrity-Policy")}} or {{httpheader("Integrity-Policy-Report-Only")}}.
-
 ## Examples
 
 ### Reporting deprecated features