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

Jump to bottom

Add an example for Interest Group including allowed reporting origins #1303

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

Add an example for Interest Group including allowed reporting origins #1303

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cf3bfba
insert a break
bass-bass Oct 14, 2024
48d05b4
add a link to interest group attributes
bass-bass Oct 14, 2024
274b447
add an example to include an allowlist of origins in interest group
bass-bass Oct 14, 2024
41c4165
insert break
bass-bass Oct 14, 2024
2a6aa25
format
bass-bass Oct 14, 2024
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
26 changes: 23 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 @@ -126,10 +126,29 @@ window.fence.reportEvent({

In the second `reportEvent` variant, fenced frames can invoke the `reportEvent` API to tell the browser to send a beacon to a specified destination URL, where macros in the URL are substituted to values registered by the buyer's worklet in `registerAdMacro` (see below). This specified URL must be a valid HTTPS URL.

This API is available in the same contexts as `reportEvent` to a preregistered destination, i.e., all documents in a fenced frame tree, with opt-in requirements for documents that are cross-origin to the mapped URL. However, there are additional restrictions on the origin of the destination URL. The interest group declaration includes an allowlist of origins that may receive reports using this mode of `reportEvent` (custom destination URL with macro substitution). If at any point a report is attempted to a disallowed origin, access to this mode of `reportEvent` will be shut off for any ad loaded from this fenced frame config, for privacy reasons (to prevent reidentification by using the allowlist to encode cross-site data about a user in binary with its choices of allowed/disallowed origins). Note that this only applies to this mode of `reportEvent`: `reportEvent` to a preregistered destination will still work.

Unlike `reportEvent` to a preregistered destination, here the browser processes the beacon by sending an HTTP GET request, as per feedback here: https://github.com/WICG/turtledove/issues/477#issuecomment-1524158476.

This API is available in the same contexts as `reportEvent` to a preregistered destination, i.e., all documents in a fenced frame tree, with opt-in requirements for documents that are cross-origin to the mapped URL. However, there are additional restrictions on the origin of the destination URL. The [interest group declaration](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#12-interest-group-attributes) includes an allowlist of origins that may receive reports using this mode of `reportEvent` (custom destination URL with macro substitution). If at any point a report is attempted to a disallowed origin, access to this mode of `reportEvent` will be shut off for any ad loaded from this fenced frame config, for privacy reasons (to prevent reidentification by using the allowlist to encode cross-site data about a user in binary with its choices of allowed/disallowed origins). Note that this only applies to this mode of `reportEvent`: `reportEvent` to a preregistered destination will still work.

### Example

Here is an example that makes the interest group include an allowlist of origins (e.g. `https://adtech.example`) to receive report events.
```
const myGroup = {
...
'ads': [
{
renderUrl: '...',
allowedReportingOrigins: [
'https://adtech.example'
]
}
],
...
};
const joinPromise = navigator.joinAdInterestGroup(myGroup);
```

### Enrollment Requirement
The reporting destination URL specified in `reportEvent`'s `destinationURL` field is required to have its [site](https://html.spec.whatwg.org/multipage/browsers.html#obtain-a-site) (scheme, eTLD+1) attested for Protected Audience API, otherwise the beacon is not allowed to be sent to this reporting destination. Please see [the Privacy Sandbox enrollment attestation model](https://github.com/privacysandbox/attestation#the-privacy-sandbox-enrollment-attestation-model).

Expand All @@ -142,7 +161,8 @@ The reporting destination URL specified in `reportEvent`'s `destinationURL` fiel
Here is an example that will substitute `${PUBLISHER_ID}` and `${SOURCE_URL_ENC}` macros based on values specified in the buyer worklet.
```
window.fence.reportEvent({
'destinationURL': 'https://adtech.example/impression?cid=555&pub_id=${PUBLISHER_ID}&site=${SOURCE_URL_ENC}&t=123'});
'destinationURL': 'https://adtech.example/impression?cid=555&pub_id=${PUBLISHER_ID}&site=${SOURCE_URL_ENC}&t=123'
});
```

In this example, the reporting destination eTLD+1 is "adtech.example". [The Privacy Sandbox enrollment attestation model](https://github.com/privacysandbox/attestation#the-privacy-sandbox-enrollment-attestation-model) requires its [site](https://html.spec.whatwg.org/multipage/browsers.html#obtain-a-site) (scheme, eTLD+1) `"https://adtech.example"` to be enrolled as defined in [site-based enrollment](https://developer.chrome.com/blog/announce-enrollment-privacy-sandbox/#site-based-enrollment). Otherwise the beacon will not be sent.
Expand Down