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

Update automatic beacon explainer for new sending behavior #808

Merged
merged 7 commits into from
Nov 8, 2023
Merged

Update automatic beacon explainer for new sending behavior #808

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
97e8f56
update automatic beacon explainer
blu25 Sep 14, 2023
dedbe93
update section on component ads
blu25 Sep 26, 2023
c0d0ad4
update to include changes from security review
blu25 Oct 9, 2023
5f68360
fix formatting
blu25 Oct 9, 2023
d28afbe
update to include changes from code review
blu25 Oct 10, 2023
8bf8260
address review comments
blu25 Oct 23, 2023
ee968ab
fix typo
blu25 Oct 26, 2023
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
update to include changes from security review
  • Loading branch information
@blu25
blu25 committed Oct 9, 2023
commit c0d0ad4ab52dcb75a1bf58e63d03c69eccc9bf18
11 changes: 5 additions & 6 deletions Fenced_Frames_Ads_Reporting.md
View file
Open in desktop
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 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. Because this is information about a frame that can be sent to a cross-origin destination, there also needs to be a way for the frame to opt in/opt out of having this information sent. To achieve this, a new `setReportEventDataForAutomaticBeacons` API can be invoked from within the fenced frame:


```
Expand All @@ -168,15 +168,14 @@ window.fence.setReportEventDataForAutomaticBeacons({
});
```

If `setReportEventDataForAutomaticBeacons` is invoked at least once in a frame's lifetime, the browser will send an automatic beacon to all registered URLs, but will only send an event data body (the information in `eventData`) with the HTTP request to destinations specified in the `destination` field.

If `setReportEventDataForAutomaticBeacons` is not invoked, the browser will not send an automatic beacon to any registered URLs.

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.

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 send an automatic beacon to all registered URLs but will not include any data with the beacon.

Automatic beacon data can be manually cleared out by calling `setReportEventDataForAutomaticBeacons` with an empty destination list.
```
window.fence.setReportEventDataForAutomaticBeacons({
Expand All @@ -185,7 +184,7 @@ window.fence.setReportEventDataForAutomaticBeacons({
});
```

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

```
<script>
Expand Down