Technical Review: Add documentation for Fenced Frames

files/en-us/web/api/fence/getnestedconfigs/index.md

@@ -0,0 +1,57 @@
+---
+title: "Fence: getNestedConfigs() method"
+short-title: getNestedConfigs()
+slug: Web/API/Fence/getNestedConfigs
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.Fence.getNestedConfigs
+---
+
+{{SeeCompatTable}}{{APIRef("Fenced Frame API")}}
+
+The **`getNestedConfigs()`** method of the
+{{domxref("Fence")}} interface returns the {{domxref("FencedFrameConfig")}}s loaded into `<fencedframe>`s embedded inside the current `<fencedframe>`.
+
+## Syntax
+
+```js-nolint
+getNestedConfigs()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+`getNestedConfigs()` has two possible return values:
+
+- An array of 20 {{domxref("FencedFrameConfig")}} objects, if the current `<fencedframe>`'s config was created using an API that supports nested configs (for example [Protected Audience](https://developer.chrome.com/docs/privacy-sandbox/protected-audience/)). Of these 20 configs, the first N configs are those registered through the API and the rest are padding configs that will navigate to `about:blank`, so that the number of configs is hidden and cannot leak any information.
+- `null` if the current `<fencedframe>`'s config was created using an API that does not support nested configs (for example [Shared Storage](/docs/Web/API/Shared_Storage_API)).
+
+## Examples
+
+```js
+// Run inside a <fencedframe>
+
+// Retrieve the configs of embedded fenced frames
+const configs = window.fence.getNestedConfigs();
+
+// Set a new fenced frame's config to equal one of the retrieved configs
+const frame = document.createElement("fencedframe");
+frame.config = configs[0];
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Fenced frames](https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/) on developer.chrome.com
+- [The Privacy Sandbox](https://developer.chrome.com/docs/privacy-sandbox/) on developer.chrome.com

files/en-us/web/api/fence/index.md

@@ -0,0 +1,50 @@
+---
+title: Fence
+slug: Web/API/Fence
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.Fence
+---
+
+{{SeeCompatTable}}{{APIRef("Fenced Frame API")}}
+
+The **`Fence`** interface of the {{domxref("Fenced Frame API", "Fenced Frame API", "", "nocode")}} contains several functions relevant to fenced frame functionality.
+
+`Fence` objects are accessed through the {{domxref("Window.fence")}} property, but they are only available to documents embedded inside {{htmlelement("fencedframe")}}s (loaded via {{domxref("FencedFrameConfig")}}s) or {{htmlelement("iframe")}}s (loaded via opaque URNs).
+
+> **Note:** See [How do `<fencedframe>`s work?](/en-US/docs/Web/API/Fenced_frame_API#how_do_fencedframes_work) for some description around `FencedFrameConfig`s and opaque URNs.
+
+{{InheritanceDiagram}}
+
+## Instance methods
+
+- {{domxref("Fence.getNestedConfigs", "getNestedConfigs()")}} {{Experimental_Inline}}
+  - : Returns the {{domxref("FencedFrameConfig")}}s loaded into `<fencedframe>`s embedded inside the current `<fencedframe>`.
+- {{domxref("Fence.reportEvent", "reportEvent()")}} {{Experimental_Inline}}
+  - : Triggers the submission of report data via a [beacon](/en-US/docs/Web/API/Beacon_API) to one ore more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://developer.chrome.com/docs/privacy-sandbox/fledge/), for the purpose of collecting ad auction results.
+- {{domxref("Fence.setReportEventDataForAutomaticBeacons", "setReportEventDataForAutomaticBeacons()")}} {{Experimental_Inline}}
+  - : Specifies event data that will be sent when a navigation occurs inside a `<fencedframe>`. This data will be sent via an automatic beacon to one or more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://developer.chrome.com/docs/privacy-sandbox/fledge/), for the purpose of collecting reporting data for ad auction results.
+
+## Examples
+
+```js
+window.fence.reportEvent({
+  eventType: "click",
+  eventData: JSON.stringify({ clickX: "123", clickY: "456" }),
+  destination: ["buyer", "seller"],
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Fenced frames](https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/) on developer.chrome.com
+- [The Privacy Sandbox](https://developer.chrome.com/docs/privacy-sandbox/) on developer.chrome.com

files/en-us/web/api/fence/reportevent/index.md

@@ -0,0 +1,67 @@
+---
+title: "Fence: reportEvent() method"
+short-title: reportEvent()
+slug: Web/API/Fence/reportEvent
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.Fence.reportEvent
+---
+
+{{SeeCompatTable}}{{APIRef("Fenced Frame API")}}
+
+The **`reportEvent()`** method of the
+{{domxref("Fence")}} interface triggers the submission of report data via a [beacon](/en-US/docs/Web/API/Beacon_API) to one or more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://developer.chrome.com/docs/privacy-sandbox/fledge/), for the purpose of collecting ad auction results.
+
+> **Note:** {{domxref("Fence.setReportEventDataForAutomaticBeacons", "setReportEventDataForAutomaticBeacons()")}} provides similar report data submission, except in that case the submission is triggered via a navigation rather than by an explicit method call.
+
+## Syntax
+
+```js-nolint
+reportEvent(event)
+```
+
+### Parameters
+
+- `event`
+  - : An object or string representing the data to send.
+    - An object value defines a specific report event that you want to send. The required properties are as follows:
+      - `eventType`
+        - : A string representing the type of event that is being reported — for example you might be interested in how many times an ad is clicked on. This string can be any relevant event name (for example [`click`](/en-US/docs/Web/API/Element/click_event)). This needs to match the event type specified in the associated {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} call in a Protected Audience API worklet.
+      - `eventData`
+        - : A string representing the data to be sent.
+      - `destination`
+        - : An array containing one or more enumerated values representing destination types. These are the involved parties that will receive the data to their registered URLs (i.e. via {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}}). The possible values are:
+          - `"buyer"`: The bidder in the ad auction.
+          - `"seller"`: The top-level seller running the ad auction.
+          - `"component-seller"`: The seller for a component auction in a multi-level auction.
+          - `"direct-seller"`: The seller that directly ran the auction the buyer bid in. If the ad was a single-level auction, the value used will be `"seller"`. If the ad was a multi-level auction, the value used will be `"component-seller"`.
+          - `"shared-storage-select-url"`: A [Shared Storage API](https://developer.chrome.com/docs/privacy-sandbox/shared-storage/) storage location, as defined in a {{domxref("WindowSharedStorage.selectURL", "Window.sharedStorage.selectURL()")}} method call.
+    - A string value represents an `eventType`, for example `"click"` (see the earlier definition of `eventType`). When an `eventType` string is passed as the value of `reportEvent()`, it triggers all Private Aggregation contributions that were made conditional on that event type (for example via {{domxref("PrivateAggregation.contributeToHistogramOnEvent()")}}) to be sent.
+
+### Return value
+
+None (`Undefined`).
+
+## Examples
+
+```js
+window.fence.reportEvent({
+  eventType: "click",
+  eventData: JSON.stringify({ clickX: "123", clickY: "456" }),
+  destination: ["buyer", "seller"],
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Fenced frames](https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/) on developer.chrome.com
+- [The Privacy Sandbox](https://developer.chrome.com/docs/privacy-sandbox/) on developer.chrome.com

files/en-us/web/api/fence/setreporteventdataforautomaticbeacons/index.md

@@ -0,0 +1,69 @@
+---
+title: "Fence: setReportEventDataForAutomaticBeacons() method"
+short-title: setReportEventDataForAutomaticBeacons()
+slug: Web/API/Fence/setReportEventDataForAutomaticBeacons
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.Fence.setReportEventDataForAutomaticBeacons
+---
+
+{{SeeCompatTable}}{{APIRef("Fenced Frame API")}}
+
+The **`setReportEventDataForAutomaticBeacons()`** method of the
+{{domxref("Fence")}} interface specifies event data that will be sent when a navigation occurs inside a {{htmlelement("fencedframe")}}. This data will be sent via an automatic [beacon](/en-US/docs/Web/API/Beacon_API) to one or more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://developer.chrome.com/docs/privacy-sandbox/fledge/), for the purpose of collecting reporting data for ad auction results.
+
+> **Note:** {{domxref("Fence.reportEvent", "reportEvent()")}} provides similar report data submission, except in that case the submission is triggered via an explicit method call rather than a navigation.
+
+## Syntax
+
+```js-nolint
+setReportEventDataForAutomaticBeacons(event)
+```
+
+### Parameters
+
+- `event`
+  - : an object representing the data to send. The possible properties are as follows:
+    - `eventType`
+      - : A string representing the type of event that is being reported. The available values are:
+        - `reserved.top_navigation_start`: An event fired when a top-level navigation begins.
+        - `reserved.top_navigation_commit`: An event fired when a top-level navigation completes.
+    - `eventData`
+      - : A string representing the data to be sent.
+    - `destination`
+      - : An array containing one or more enumerated values representing destination types. These are the involved parties that will receive the data to their registered URLs (i.e. via {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}}). The possible values are:
+        - `"buyer"`: The bidder in the ad auction.
+        - `"seller"`: The top-level seller running the ad auction.
+        - `"component-seller"`: The seller for a component auction in a multi-level auction.
+        - `"direct-seller"`: The seller that directly ran the auction the buyer bid in. If the ad was a single-level auction, the value used will be `"seller"`. If the ad was a multi-level auction, the value used will be `"component-seller"`.
+        - `"shared-storage-select-url"`: A [Shared Storage API](https://developer.chrome.com/docs/privacy-sandbox/shared-storage/) storage location, as defined in a {{domxref("WindowSharedStorage.selectURL", "Window.sharedStorage.selectURL()")}} method call.
+    - `once` {{optional_inline}}
+      - : A boolean value. If set to `true`, the automatic beacon will only be sent for the next event, and beacons will not be sent for subsequent events until `setReportEventDataForAutomaticBeacons()` is invoked again. For example, 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. This property defaults to `false`.
+
+### Return value
+
+None (`Undefined`).
+
+## Examples
+
+```js
+window.fence.setReportEventDataForAutomaticBeacons({
+  eventType: "reserved.top_navigation_start",
+  eventData: "an example string",
+  destination: ["seller", "buyer"],
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Fenced frames](https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/) on developer.chrome.com
+- [The Privacy Sandbox](https://developer.chrome.com/docs/privacy-sandbox/) on developer.chrome.com

files/en-us/web/api/fenced_frame_api/communication_with_embedded_frames/index.md

@@ -0,0 +1,60 @@
+---
+title: Communication with embeded frames
+slug: Web/API/Fenced_frame_API/Communication_with_embedded_frames
+page-type: guide
+---
+
+{{DefaultAPISidebar("Fenced Frame API")}}
+
+This article provides information on how communication differs between an embedder and content embedded inside different types of frame (i.e. an {{htmlelement("iframe")}} and a {{htmlelement("fencedframe")}}), and how passed data can be stored.
+
+## How to communicate between the embedder and an `<iframe>`
+
+![Diagram illustrating the difference between local storage and shared storage and communication with an iframe, as explained below](iframe-storage-communication.png)
+
+When the third-party code is embedded in an `<iframe>`, the `<iframe>` and the embedder can send messages freely to each other to request data to be written into their [shared storage](/en-US/docs/Web/API/Shared_Storage_API). The embedder can send a request to that `<iframe>` to write data into its own third-party storage with a cross-document communication channel using {{domxref("Window.postMessage()")}}. The third party can also send `postMessage()` requests to the embedder.
+
+From the `<iframe>`, you can listen to a [`message`](/en-US/docs/Web/API/Window/message_event) event that comes from the embedder. When the embedder dispatches a message to the `<iframe>` using `postMessage()`, the `<iframe>` can take that data and store it in its own shared storage. Conversely, the `<iframe>` can dispatch a message that the embedder can listen to, and respond by writing data into its shared storage.
+
+## How to communicate between the embedder and a `<fencedframe>`
+
+Sometime in the future, fenced frames will likely become more common as they will be used for use cases such as displaying targeted ads selected via the [Protected Audience API](https://developer.chrome.com/en/docs/privacy-sandbox/fledge/) and {{domxref("WindowSharedStorage.selectURL()")}}. Communicating between `<fencedframe>`s and other pages outside the `<fencedframe>` on the page is intentionally limited, but one method of communication between the embedder and shared storage worklets does exist — {{domxref("FencedFrameConfig.setSharedStorageContext()")}}.
+
+> **Note:** Within the same `<fencedframe>` tree, communication between frames is allowed. For example, a root `<fencedframe>` can send a message to a child `<iframe>` in its own tree, and a child `<iframe>` can send a message to the parent `<fencedframe>`.
+
+Let's look at a more complex example that uses a Select URL output gate operation to render an ad in a `<fencedframe>`.
+
+![A complex embedding situation with an embedder that is embedding an iframe, which is embedding a fencedframe, which is embedding an iframe](multiple-embed-levels.png)
+
+In this example, a publisher asks a third-party content provider to render some content on the page. The content chosen with {{domxref("WindowSharedStorage.selectURL()")}} is rendered in a `<fencedframe>`, and the content contains an `<iframe>` from a measurement provider. Note that a publisher can represent any entity that is embedding a third-party `<fencedframe>`. Also, a measurement provider represents any nested third-party code running in a `<fencedframe>` of a different third party.
+
+To pass data into a `<fencedframe>` to be used in a shared storage worklet, the embedder can set the data in a {{domxref("FencedFrameConfig")}}. That value will be available as {{domxref("WorkletSharedStorage.context")}} inside the shared storage worklet. This data is not available outside a worklet, and can only be accessed inside a secure and private environment that a shared storage worklet provides.
+
+![A publisher created a fencedframeconfig using selectURL, which can set contextual data using setSharedStorageContext that will then be available in a shared storage worklet](share-contextual-data.png)
+
+When a `selectURL()` call returns a `FencedFrameConfig`, the frame embedder can pass in data by calling `setSharedStorageContext(data)`:
+
+```js
+const fencedFrameConfig = await window.sharedStorage.selectURL('creative-rotation', urls, {
+  // …
+  resolveToConfig: true
+});
+
+fencedFrameConfig.setSharedStorageContext(‘some-data’);
+
+// Navigate the fenced frame to the config.
+document.getElementById('my-fenced-frame').config = fencedFrameConfig;
+```
+
+`setSharedStorageContext(data)` must be called on the `fencedFrameConfig` before the intended `<fencedframe>` element recipient has its `config` attribute set to `fencedFrameConfig`, as this triggers the frame to navigate.
+
+Inside a shared storage worklet, `WorkletSharedStorage.context` can then be accessed to retrieve the data:
+
+```js
+class ReportingOperation {
+  async run() {
+    sharedStorage.set(‘some-data-from-embedder’, sharedStorage.context)
+  }
+}
+register('send-report', ReportingOperation);
+```