Add explainer for "once" parameter in setReportEventDataForAutomaticB…

…eacons (#718)

* add onlyForNextAutomaticBeacon to explainer

* add manual clearing part

* update variable name to reflect change in code review

* clarify behavior and reason for adding

* address review comments

Fenced_Frames_Ads_Reporting.md

@@ -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'],
 });
 ```
 
@@ -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:
 
 ```
@@ -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.