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 1 commit 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
1 commit
Select commit
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
10 changes: 7 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.

```
window.fence.setReportEventDataForAutomaticBeacons({
Expand All @@ -324,6 +326,8 @@ 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.

#### 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