Explain reportEvent to custom destination urls (with macro substituti…

…on) (#763)

* Explain reportEvent to custom destination urls (with macro substitution)

* Update Fenced_Frames_Ads_Reporting.md

Co-authored-by: Paul Jensen <[email protected]>

* Update Fenced_Frames_Ads_Reporting.md

Co-authored-by: Paul Jensen <[email protected]>

* Update Fenced_Frames_Ads_Reporting.md

Co-authored-by: Paul Jensen <[email protected]>

* sets -> variants

* Update Fenced_Frames_Ads_Reporting.md

* Update Fenced_Frames_Ads_Reporting.md

---------

Co-authored-by: Paul Jensen <[email protected]>

Fenced_Frames_Ads_Reporting.md

@@ -45,14 +45,15 @@ The following summarizes the sequence of events for the buyer and seller. Distin
 The following new APIs will be added for achieving this.
 
 
-## reportEvent
+## reportEvent (preregistered destination URL)
 
-Fenced frames can invoke the `reportEvent` API to tell the browser to send a beacon with event data to a URL registered by the worklet in `registerAdBeacon` (see below). Depending on the declared `destination`(s), the beacon is sent to either the buyer's and/or the seller's registered URL. Examples of such events are mouse hovers, clicks (which may or may not lead to navigation e.g. video player control element clicks), etc.
+There are two variants of the `reportEvent` API for event-level reporting that are invoked with different sets of parameters. In the first variant, fenced frames can invoke the `reportEvent` API to tell the browser to send a beacon with event data to a URL registered by the worklet in `registerAdBeacon` (see below). Depending on the declared `destination`, the beacon is sent to either the buyer's or the seller's registered URL. Examples of such events are mouse hovers, clicks (which may or may not lead to navigation e.g. video player control element clicks), etc.
 
-This API is available from same-origin frames within the initial rendered ad document and across subsequent same-origin navigations, but it's no longer available after cross-origin navigations or in cross-origin subframes. (For this API, for chains of redirects, the requestor is considered same-origin with the target only if it is same-origin with all redirect URLs in the chain.) This way, the ad may redirect itself without losing access to reporting, but other sites can't send spurious reports.
+This API is available from all documents in a fenced frame that are same-origin to the mapped URL of the fenced frame config (i.e., the ad creative URL that won the Protected Audience auction).
 
 The browser processes the beacon by sending an HTTP POST request, like the existing [navigator.sendBeacon](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon).
 
+Note `window.fence` here is a new namespace for APIs that are only available from within a fenced frame. In the interim period when FLEDGE supports rendering the winning ad in an iframe, `window.fence` will also be available in such an iframe.
 
 ### Parameters
 
@@ -104,8 +105,25 @@ window.fence.reportEvent({
 });
 ```
 
+## reportEvent (custom destination URL with substitution of preregistered macros)
 
-Note `window.fence` here is a new namespace for APIs that are only available from within a fenced frame. In the interim period when FLEDGE supports rendering the winning ad in an iframe, `window.fence` will also be available in such an iframe.
+In the second `reportEvent` variant, fenced frames can invoke the `reportEvent` API to tell the browser to send a beacon to a specified destination URL, where macros in the URL are substituted to values registered by the buyer's worklet in `registerAdMacro` (see below). This specified URL must be a valid HTTPS URL.
+
+This API is available in the same contexts as `reportEvent` to a preregistered destination, i.e., documents that are same-origin to the fenced frame config's mapped URL. However, there are additional restrictions on the origin of the destination URL. The interest group declaration includes an allowlist of origins that may receive reports using this mode of `reportEvent` (custom destination URL with macro substitution). If at any point a report is attempted to a disallowed origin, access to this mode of `reportEvent` will be shut off for any ad loaded from this fenced frame config, for privacy reasons (to prevent reidentification by using the allowlist to encode cross-site data about a user in binary with its choices of allowed/disallowed origins). Note that this only applies to this mode of `reportEvent`: `reportEvent` to a preregistered destination will still work.
+
+Unlike `reportEvent` to a preregistered destination, here the browser processes the beacon by sending an HTTP GET request, as per feedback here: https://github.com/WICG/turtledove/issues/477#issuecomment-1524158476.
+
+### Parameters
+
+**Destination URL:** Includes the desired destination URL for the report, with macros to be substituted based on the buyer worklet's specified values.
+
+### Example
+
+Here is an example that will substitute `${PUBLISHER_ID}` and `${SOURCE_URL_ENC}` macros based on values specified in the buyer worklet.
+```
+window.fence.reportEvent({
+  'destinationURL': 'https://adtech.example/impression?cid=555&pub_id=${PUBLISHER_ID}&site=${SOURCE_URL_ENC}&t=123'});
+```
 
 ## registerAdBeacon
 
@@ -127,6 +145,21 @@ registerAdBeacon({
 });
 ```
 
+## registerAdMacro
+Bidder worklets are able to register macros with the browser in their `reportWin()` function. The registered macro values are used to substitute macros in the destination URL of the `reportEvent()` API's parameter.
+
+### Parameters
+Two strings.
+**macro name** It’s case sensitive, e.g., `“PUBLISHER_ID”`. 
+
+**macro value** The value of the macro that is used to substitute the macro (e.g., ${PUBLISHER_ID}) in `reportEvent()` API’s destination URL parameter.
+
+### Example
+```
+registerAdMacro(‘PUBLISHER_ID’, ‘123a’);
+registerAdMacro(‘SOURCE_URL_ENC’, ‘http%3A%2F%2Fpub%2Eexample%2Fpage’);
+```
+
 ## Support for Attribution Reporting 
 ### Goals
 *   While fenced frames still have unrestricted network access and FLEDGE supports event-level reporting, the solution below takes advantage of the `registerAdBeacon`/`reportEvent` information flow to enable [registering attribution sources](https://github.com/WICG/attribution-reporting-api/blob/main/EVENT.md#registering-attribution-sources). [ARA attribution triggering](https://github.com/WICG/attribution-reporting-api/blob/main/EVENT.md#triggering-attribution) is unchanged for registered FLEDGE impressions.