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 explainer for "once" parameter in setReportEventDataForAutomaticBeacons #718

Merged
merged 5 commits into from
Sep 11, 2023
Merged

Add explainer for "once" parameter in setReportEventDataForAutomaticBeacons #718

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
381e6cc
add onlyForNextAutomaticBeacon to explainer
blu25 Jul 13, 2023
8e0b35e
add manual clearing part
blu25 Jul 19, 2023
4f3ba5d
update variable name to reflect change in code review
blu25 Jul 20, 2023
d0fc15c
clarify behavior and reason for adding
blu25 Jul 27, 2023
92a921f
address review comments
blu25 Jul 31, 2023
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
23 changes: 22 additions & 1 deletion Fenced_Frames_Ads_Reporting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ Since the `reserved.top_navigation` beacons are automatically generated by the b
window.fence.setReportEventDataForAutomaticBeacons({
'eventType': 'reserved.top_navigation',
'eventData': 'an example string',
'destination':['seller', 'buyer']
'destination': ['seller', 'buyer'],
});
```

Expand All @@ -177,6 +177,14 @@ If invoked multiple times, the latest invocation before the top-level navigation

If `setReportEventDataForAutomaticBeacons` is not invoked, the browser will not send an automatic beacon because the `destination` is unknown.

An automatic beacon can be manually cleared out by calling `setReportEventDataForAutomaticBeacons` with an empty destination list.
```
window.fence.setReportEventDataForAutomaticBeacons({
'eventType': 'reserved.top_navigation',
'destination': [],
});
```

`setReportEventDataForAutomaticBeacons` can also be invoked in the click handler of an anchor tag, and will be sent on navigation:

```
Expand All @@ -196,6 +204,19 @@ function addBeaconData(element) {

The beacon data will be in place by the time that the navigation starts. When the navigation commits, the automatic beacon will be sent out with event data set to "link1 was clicked.".

The dictionary passed into `setReportEventDataForAutomaticBeacons` also takes an optional `once` boolean that defaults to false. If `once` is set to true, the automatic beacon will only be sent for the next `reserved.top_navigation` event. Beacons will not be sent for subsequent `reserved.top_navigation` events until `setReportEventDataForAutomaticBeacons` is invoked again. When used with a click handler, this can be used to send beacons only for specific top-level navigations, rather than for every top-level navigation.

For example, if a frame has multiple links that can perform top-level navigations, but only one of the links should have an automatic beacon associated with it, `setReportEventDataForAutomaticBeacons()` can be called in that link's click handler with `once` set to true. This will ensure that, if another link is clicked after the link with the associated automatic beacon, that other link will not result in a beacon being sent out.

```
window.fence.setReportEventDataForAutomaticBeacons({
'eventType': 'reserved.top_navigation',
'eventData': 'an example string',
'destination': ['seller', 'buyer'],
'once': true,
});
```

# Support for Ad Components
## Goal
When a rendered ad is composed of [multiple pieces](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces), it is useful to detect user clicks that happened on ad components.
Expand Down