COEPViolationReportBody

Instance properties

COEPViolationReportBody.type Read only

A string representing what kind of cross-origin embedding caused the violation.

COEPViolationReportBody.blockedURL Read only

A string containing the URL of the blocked resource.

COEPViolationReportBody.destination Read only Non-standard

A string indicating the Request.destination of the blocked resource.

COEPViolationReportBody.disposition Read only

A string indicating whether the violation was enforced or only reported.

Description

A document's policies for loading and embedding cross-origin resources that are requested in no-cors mode are configured and enforced using the Cross-Origin-Embedder-Policy HTTP header, and may also be reported but not enforced using the Cross-Origin-Embedder-Policy-Report-Only header.

COEP policy violations may be reported whenever a policy set by those headers blocks (or would block) the loading of a resource.

You can report COEP violations within the page in which they are triggered using the Reporting API. To do this we construct a new ReportingObserver object to listen for reports with the type "coep", passing a callback that will receive and log the reports. The callback will then return Report instances for each COEP violation, which have the type of coep and a body property that is an object of this type.

The object has this format. Note that the specific cause of the violation is indicated by the body.type property. In this case it is corp, which indicates that the violating resource did not set a CORP that allowed it to be loaded in the document's origin.

{
  "type": "coep",
  "url": "https://url-of-page-attempting-to-load-resource-in-violation",
  "body": {
    "type": "corp",
    "blockedURL": "https://url-of-blocked-resource",
    "destination": "image",
    "disposition": "enforce"
  }
}

Reports can also be sent as a JSON object in a POST to a reporting server endpoint. The reporting server endpoint name is specified in the report-to parameter when setting Cross-Origin-Embedder-Policy or Cross-Origin-Embedder-Policy-Report-Only. Valid endpoint names and their mapping to a particular URL are defined using the Reporting-Endpoints header.

The report format is almost exactly the same as for the Report object, except that it additionally includes age and user_agent fields.

{
  "age": 412139,
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
  "type": "coep",
  "url": "https://url-of-page-attempting-to-load-resource-in-violation",
  "body": {
    "type": "corp",
    "blockedURL": "https://url-of-blocked-resource",
    "destination": "image",
    "disposition": "enforce"
  }
}

Examples

Reporting using the API

This example shows how you can obtain COEP violation reports using a ReportingObserver.

First consider the case where we have an HTML file hosted on the origin https://example.com, which includes in its body an <img> element that sets as its source the (cross-origin) resource some-image.png. Since the element does not set the cross-origin attribute attribute, it will be requested in no-cors mode. By default, if some-image.png is not served with the Cross-Origin-Embedder-Policy header, this request will succeed.

<img src="https://another-example.com/some-image.png" />

In order to ensure that the document only loads cross-origin resources that indicate that they are safe to load in our document origin, we can set the Cross-Origin-Embedder-Policy header with the require-corp directive as shown:

Cross-Origin-Embedder-Policy: require-corp

This header enforces that all resources must be served with the Cross-Origin-Resource-Policy header and a value of cross-origin in order to be loaded into the document's origin (https://example.com). Provided the server hosting some-image.png doesn't set the header we don't need to do anything else to trigger a COEP violation.

To observe violations within the page, we construct a new ReportingObserver object to listen for reports with the type "coep", passing a callback that will receive and log the reports. This code needs to be loaded before the script that causes the violation, in the same page:

const options = {
  types: ["coep"],
  buffered: true,
};

const observer = new ReportingObserver((reports, observer) => {
  reports.forEach((violation) => {
    console.log(violation);
    console.log(JSON.stringify(violation));
  });
}, options);

observer.observe();

Above, we log each violation report object and a JSON-string version of the object, which might look similar to the object below. Note that the type is "coep" and that the body is an object of this type (a CSPViolationReportBody).

{
  "type": "coep",
  "url": "https://example.com",
  "body": {
    "type": "corp",
    "blockedURL": "https://another-example.com/some-image.png",
    "destination": "image",
    "disposition": "enforce"
  }
}

The same report would be generated if we set Cross-Origin-Embedder-Policy-Report-Only in the same way, except that the disposition would be set to "reporting".

Sending a report to a reporting endpoint

Configuring a web page to send a COEP report to a reporting server endpoint is almost the same as the previous example. The only difference is that we need to specify a reporting endpoint where we want the reports to be sent, using the Reporting-Endpoints response header, and then reference these in the report-to parameter when setting the policy.

You can see this below, where we define the endpoint named coep-endpoint and then reference it in our policy:

Reporting-Endpoints: coep-endpoint="https://some-example.com/coep"
Cross-Origin-Embedder-Policy: require-corp; report-to="coep-endpoint"

The violation report will then be sent as a JSON object in a POST to the endpoint referenced by coep-endpoint.

The report object is almost the same as provided by the Reporting API, except that it has the additional fields age and user_agent properties. Its type is "coep" and that the body is a JSON serialized CSPViolationReportBody object.

[
  {
    "age": 717139,
    "body": {
      "blockedURL": "https://another-example.com/some-image.png",
      "destination": "image",
      "disposition": "enforce",
      "type": "corp"
    },
    "type": "coep",
    "url": "https://example.com",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
  }
]

The same report would be generated if we set Cross-Origin-Embedder-Policy-Report-Only in the same way, except that the disposition would be set to "reporting".

Specifications

Browser compatibility

See also

• Reporting-Endpoints
• Reporting API
• The Reporting API