diff --git a/files/en-us/web/api/crashreport/index.md b/files/en-us/web/api/crashreport/index.md index b075c0afb2bb8c0..01342d1865386d7 100644 --- a/files/en-us/web/api/crashreport/index.md +++ b/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` diff --git a/files/en-us/web/api/crashreportcontext/index.md b/files/en-us/web/api/crashreportcontext/index.md index d5d02608722a0a7..eb77c9e21c1da8f 100644 --- a/files/en-us/web/api/crashreportcontext/index.md +++ b/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 diff --git a/files/en-us/web/api/permissionspolicyviolationreport/index.md b/files/en-us/web/api/permissionspolicyviolationreport/index.md index b4cb683e0fd4c9c..b673a34bf7decc6 100644 --- a/files/en-us/web/api/permissionspolicyviolationreport/index.md +++ b/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 `` element. +Violations of the policy may also be reported but not enforced using the {{httpheader("Permissions-Policy-Report-Only")}} HTTP header, or a `` 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) diff --git a/files/en-us/web/api/reporting_api/index.md b/files/en-us/web/api/reporting_api/index.md index 9591b4c0d24f1f4..0446628a526f1b9 100644 --- a/files/en-us/web/api/reporting_api/index.md +++ b/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 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 diff --git a/files/en-us/web/http/reference/headers/permissions-policy-report-only/index.md b/files/en-us/web/http/reference/headers/permissions-policy-report-only/index.md new file mode 100644 index 000000000000000..8fd33c8468e06a3 --- /dev/null +++ b/files/en-us/web/http/reference/headers/permissions-policy-report-only/index.md @@ -0,0 +1,114 @@ +--- +title: Permissions-Policy-Report-Only header +short-title: Permissions-Policy-Report-Only +slug: Web/HTTP/Reference/Headers/Permissions-Policy-Report-Only +page-type: http-header +status: + - experimental +browser-compat: http.headers.Permissions-Policy-Report-Only +sidebar: http +--- + +{{SeeCompatTable}} + +The HTTP **`Permissions-Policy-Report-Only`** {{Glossary("response header")}} provides a mechanism for website administrators to report on violations of a {{HTTPHeader("Permissions-Policy")}} without enforcing them. +This allows testing and fixing of [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) issues before a policy is deployed. + +The syntax and behavior is exactly the same as for `Permissions-Policy` except: + +- The policy is not enforced. +- Policy violation report objects ({{domxref("PermissionsPolicyViolationReport")}}) have a `body.disposition` value of `"report"` instead of `"enforce"`. + +See {{HTTPHeader("Permissions-Policy")}} for more information (most of its content has not been duplicated below). + + + + + + + + +
Header type{{Glossary("Response header")}}
+ +## Syntax + +```http +# Single directive +Permissions-Policy-Report-Only: = + +# Single directive with reporting endpoint +Permissions-Policy-Report-Only: =;report-to= + +# Multiple directives, with and without server reporting endpoints +Permissions-Policy-Report-Only: =, =;report-to=, ... +``` + +## Examples + +### Basic usage + +SecureCorp Inc. wants to disable the {{domxref("Geolocation")}} API in its application. +Before rolling out the policy using `Permissions-Policy`, it adds the `Permissions-Policy-Report-Only` and {{HTTPHeader("Reporting-Endpoints")}} headers as shown below: + +```http +Reporting-Endpoints: geo_endpoint="https://example.com/reports" +Permissions-Policy-Report-Only: geolocation=();report-to=geo_endpoint +``` + +By specifying `geolocation=()` for the origin list, it is a violation for any browsing context to access geolocation (this includes `