Update automatic beacon explainer for new sending behavior (#808)

* update automatic beacon explainer

* update section on component ads

* update to include changes from security review

* fix formatting

* update to include changes from code review

* address review comments

* fix typo

Fenced_Frames_Ads_Reporting.md

@@ -15,7 +15,7 @@ From a privacy perspective, it is also important to note that the additional inf
 
 # Design
 
-The following summarizes the sequence of events for the buyer and seller. Distinguishing these flows here, since in principle, one should be able to report without the help of the other.
+The following summarizes the sequence of events for the buyer and seller. Distinguishing these flows here, since in principle, one should be able to report without the help of the other but with an opt-in from the ad's origin for maintaining web's security principles for origins.
 
 ![high level diagram](assets/fenced_frames_reporting.png)
 
@@ -190,8 +190,7 @@ As mentioned in the explainer above, `reportEvent` beacons are POST requests and
 
 ### API to populate event data for reserved.top_navigation
 
-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. 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:
 
 ```
 window.fence.setReportEventDataForAutomaticBeacons({
@@ -201,16 +200,15 @@ window.fence.setReportEventDataForAutomaticBeacons({
 });
 ```
 
+If `setReportEventDataForAutomaticBeacons` is invoked, the browser will send an automatic beacon to all URLs registered via registerAdBeacon for the given event, but it will only send an event data body (the information in eventData) with the HTTP request to destinations specified in the destination field. This means that invoking setReportEventDataForAutomaticBeacons acts as an opt-in by the fenced frame document to allow sending the beacon to all registered URLs, aligning with cross-origin security principles.
 
-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.
-
-If invoked multiple times, the latest invocation before the top-level navigation would be the one that’s honored.
+If `setReportEventDataForAutomaticBeacons` is not invoked, the browser will not send an automatic beacon to any registered URLs.
 
-`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.
+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 `setReportEventDataForAutomaticBeacons` is not invoked, the browser will not send an automatic beacon because the `destination` is unknown.
+If invoked multiple times, the latest invocation before the top-level navigation would be the one that’s honored.
 
-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',
@@ -237,9 +235,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 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 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 not result in an automatic beacon being sent out.
 
 ```
 window.fence.setReportEventDataForAutomaticBeacons({
@@ -265,7 +263,7 @@ For fenced frames rendering the ad components under the top-level ad fenced fram
 * Invocation of the `reportEvent` API from an ad component fenced frame is disallowed.
 * The only supported beacon to be sent from an ad component fenced frame is the `reserved.top_navigation` automatic beacon. Note this beacon is gated on a user activation (e.g. click).
 * To ensure that there is no arbitrary data that can be received at the server from the component ad, the `eventData` field via `window.fence.setReportEventDataForAutomaticBeacons`, if specified, will be ignored. This ensures that information from the component ad URL is not revealed in the event report, or else it could lead to the join of two independently k-anonymous URLs (parent and component ad) at the receiving server.
-* To send the beacon from a component fenced frame, `window.fence.setReportEventDataForAutomaticBeacons` must be invoked within the ad component fenced frame with `eventType` set to `'reserved.top_navigation'`. The beacon will be sent when there is a user activation (e.g. click) on the ad component fenced frame, which results in a top-level navigation.
+* `reserved.top_navigation` beacons will be sent from a component fenced frame (with no event data) when there is a user activation (e.g. click) on the ad component fenced frame, which results in a top-level navigation. The ad component must still opt in using `setReportEventDataForAutomaticBeacons` before the beacon can send.
 
 ```
 window.fence.setReportEventDataForAutomaticBeacons({