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.

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

Update automatic beacon explainer for new sending behavior #808

Merged
merged 7 commits into from
Nov 8, 2023
Next Next commit
update automatic beacon explainer
  • Loading branch information
blu25 committed Sep 14, 2023
commit 97e8f56d0b5a76a9928caa5710e0793dbf4de8cb
16 changes: 8 additions & 8 deletions Fenced_Frames_Ads_Reporting.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ As mentioned in the explainer above, `reportEvent` beacons are POST requests and

### API to populate event data for reserved.top_navigation

blu25 marked this conversation as resolved.
Show resolved Hide resolved
Since the `reserved.top_navigation` beacons are automatically generated by the browser, there needs to be some way for those beacons to be associated with a destination and include event data, as it happens in `reportEvent` generated beacons. To achieve this, a new `setReportEventDataForAutomaticBeacons` API can be invoked from within the fenced frame:
Since the `reserved.top_navigation` beacons are automatically generated by the browser, there needs to be some way for those beacons to include event data, as it happens in `reportEvent` generated beacons. To achieve this, a new `setReportEventDataForAutomaticBeacons` API can be invoked from within the fenced frame:


```
Expand All @@ -169,23 +169,23 @@ window.fence.setReportEventDataForAutomaticBeacons({
```


Currently, the only `eventType` that `setReportEventDataForAutomaticBeacons` allows is `'reserved.top_navigation'`. Note that the script invoking this API can volunteer this information to a given destination type or not, similar to `reportEvent`, using the `destination` field.
Currently, the only `eventType` that `setReportEventDataForAutomaticBeacons` allows is `'reserved.top_navigation'`. Note that the script invoking this API can volunteer the information in `eventData` to a given destination type or not, similar to `reportEvent`, using the `destination` field.

If invoked multiple times, the latest invocation before the top-level navigation would be the one that’s honored.

`eventData` is optional, and can be empty. If `eventData` is not specified, or is empty, the automatic beacon will still be sent but without an event data body in the HTTP request.
If a destination has a registered URL, but the destination is not specified in the `destination` field, an automatic beacon will be sent to the registered URL, but an event data body (the information in `eventData`) will not be included in the HTTP request.

If `setReportEventDataForAutomaticBeacons` is not invoked, the browser will not send an automatic beacon because the `destination` is unknown.
If `setReportEventDataForAutomaticBeacons` is not invoked, the browser will send an automatic beacon to all registered URLs but will not include any data with the beacon.

An automatic beacon can be manually cleared out by calling `setReportEventDataForAutomaticBeacons` with an empty destination list.
Automatic beacon data 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:
`setReportEventDataForAutomaticBeacons` can also be invoked in the click handler of an anchor tag, and its `eventData` will be sent on navigation:

```
<script>
Expand All @@ -204,9 +204,9 @@ 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.
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 include data for the next `reserved.top_navigation` event. Beacons will not include data for subsequent `reserved.top_navigation` events until `setReportEventDataForAutomaticBeacons` is invoked again. When used with a click handler, this can be used to send beacon data 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.
For example, if a frame has multiple links that can perform top-level navigations, but only one of the links is of interest for analytics purposes, `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 result in an empty automatic beacon being sent out, which can be discarded by the server.

```
window.fence.setReportEventDataForAutomaticBeacons({
Expand Down