Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Explainer update for cross-origin automatic beacon data support. #1386

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Explainer update for cross-origin automatic beacon data support. #1386

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3070063
cross origin data setting updates
blu25 Jan 17, 2025
d2906cb
mention root and subframe use cases
blu25 Jan 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions Fenced_Frames_Ads_Reporting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -309,11 +309,13 @@ window.fence.setReportEventDataForAutomaticBeacons({

#### Cross-Origin Support

Data for automatic beacons can only be set by documents that are same-origin to the mapped URL of the fenced frame config. However, cross-origin documents in child iframes of the main ad frame can still send automatic beacons, if the document and the data are **both** opted in.
Documents that are cross-origin to the mapped URL of the fenced frame config of the main ad frame can send automatic beacons if **both** it and the root ad frame are opted in.

A cross-origin document will be considered opted into sending automatic beacons if it is served with the response header `Allow-Fenced-Frame-Automatic-Beacons: true`.
The root frame opts in by being served with the response header `Allow-Cross-Origin-Event-Reporting: true`.

To opt in the data, the dictionary passed into `setReportEventDataForAutomaticBeacons` takes an optional `crossOriginExposed` boolean that defaults to false. If set to true, the automatic beacon data can be used if a cross-origin document wants to send an automatic beacon and is opted in. A document will use the data of the first ancestor frame that has automatic beacon data registered for the event type being sent.
A cross-origin document opts in by being served with the response header `Allow-Fenced-Frame-Automatic-Beacons: true`.

To use data for cross-origin automatic beacons, the dictionary passed into `setReportEventDataForAutomaticBeacons` takes an optional `crossOriginExposed` boolean that defaults to false. If set to true, the automatic beacon data can be used if a cross-origin document wants to send an automatic beacon and is opted in. A document will use the data of the first ancestor frame that has automatic beacon data registered for the event type being sent.
blu25 marked this conversation as resolved.
Show resolved Hide resolved

```
window.fence.setReportEventDataForAutomaticBeacons({
Expand All @@ -324,6 +326,12 @@ window.fence.setReportEventDataForAutomaticBeacons({
});
```

Note that a cross-origin document calling `setReportEventDataForAutomaticBeacons` with `crossOriginExposed` will count as the document itself opting in to automatic beacons, negating the need for the document to be served with the `Allow-Fenced-Frame-Automatic-Beacons: true` header.

This allows for the following use cases:
- A root frame is served with `Allow-Cross-Origin-Event-Reporting: true`, and a cross-origin subframe sets automatic beacon data with `crossOriginExposed=true`. Automatic beacons triggered from the subframe will send with the data that was set in the subframe.
- A root ad frame is served with `Allow-Cross-Origin-Event-Reporting: true` and sets automatic beacon data with `crossOriginExposed=true`. A cross-origin subframe is served with `Allow-Fenced-Frame-Automatic-Beacons: true`. Automatic beacons triggered from the subframe will send with the data that was set in the root frame.

#### Credentials in Beacons

When 3rd party cookies are enabled, automatic beacon requests only (not beacons sent manually through `reportEvent`) allow credentials (cookies) to be set in headers. This was requested by https://github.com/WICG/turtledove/issues/866 in order to help with migration and ARA debugging. These requests are subject to CORS and only occur after opt-in by virtue of calling the `setReportEventDataForAutomaticBeacons` API or using the `Allow-Fenced-Frame-Automatic-Beacons: true` response header in cross-origin iframes/component ad frames.
Expand Down
Loading