The HTTP Permissions-Policy-Report-Only response header provides a mechanism for website administrators to report on violations of a Permissions-Policy without enforcing them. This allows testing and fixing of 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 (PermissionsPolicyViolationReport) have a body.disposition value of "report" instead of "enforce".

See Permissions-Policy for more information (most of its content has not been duplicated below).

Syntax

# Single directive
Permissions-Policy-Report-Only: <directive>=<allowlist>

# Single directive with reporting endpoint
Permissions-Policy-Report-Only: <directive>=<allowlist>;report-to=<endpoint>

# Multiple directives, with and without server reporting endpoints
Permissions-Policy-Report-Only: <directive>=<allowlist>, <directive>=<allowlist>;report-to=<endpoint>, ...

Examples

Basic usage

SecureCorp Inc. wants to disable the Geolocation API in its application. Before rolling out the policy using Permissions-Policy, it adds the Permissions-Policy-Report-Only and Reporting-Endpoints headers as shown below:

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 <iframe>s), regardless of origin. The report-to parameter indicates that reports will be sent to the endpoint named geo_endpoint. The mapping between geo_endpoint and the URL where reports are to be sent is provided in Reporting-Endpoints.

A violation occurs when a page attempts to use the blocked feature, for example:

navigator.geolocation.getCurrentPosition(
  () => {},
  () => {},
);

The report payload sent to the endpoint will have the same structure as the JSON sample shown below. This is the same as a report for Permissions-Policy except for the value of body.disposition.

[
  {
    "age": 48512,
    "body": {
      "columnNumber": 29,
      "disposition": "report", // A violation that is reported but not enforced
      "lineNumber": 44,
      "message": "Permissions policy violation: geolocation access has been blocked because of a permissions policy applied to the current document.",
      "featureId": "geolocation",
      "sourceFile": "https://example.com/"
    },
    "type": "permissions-policy-violation",
    "url": "https://example.com/",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36"
  }
]

Specifications

Browser compatibility

See also

• Permissions Policy
• Document.featurePolicy and FeaturePolicy
• Content-Security-Policy
• Referrer-Policy
• Reporting-Endpoints
• PermissionsPolicyViolationReport
• ReportingObserver
• Reporting API