Skip to content

Latest commit

 

History

History
40 lines (24 loc) · 2.99 KB

fenced_frame_config.md

File metadata and controls

40 lines (24 loc) · 2.99 KB
Raw

Fenced frame configs

Introduction

For use cases involving APIs that access cross-site data, we need to be able to load a fenced frame with content determined by the API without revealing information about the content to the embedding context. For example, with interest-based ads in Protected Audience, the winning ad that's returned from the auction depends on the user's cross-site interest group data, which we don't want to expose to the site that calls the auction. This document proposes a web-platform way of loading content into a fenced frame using an opaque object.

Proposed solution

<fencedframe> has an attribute config, rather than src. APIs like FLEDGE return a FencedFrameConfig object defined by our WebIDL. This object has a series of fields that specify the behavior desired by the API (e.g. the ad url, width and height as seen from within the fenced frame, etc.). When the embedder stores this object into the config attribute, the fenced frame loads the context accordingly.

In order to hide information as described above, the browser redacts FencedFrameConfig before sending it to the embedder. This means that certain fields which are sensitive, like the ad url, are replaced with a string opaque. The embedder may see whether there is a value defined for that field, but not what the value is. Likewise, when the embedder requests that a config be loaded into the fenced frame, the browser is responsible for looking up the config in a data structure in order to access the unredacted information.

Protected Audience Example

When the SSP JS invokes the Protected Audience API to run the ad auction, it gets back the FencedFrameConfig as the result, which is then used for rendering the fenced frame. This FencedFrameConfig has an opaque src, which maps to an actual ad url which is part of the interest group.

navigator.runAdAuction(myAuctionConfig).then((auctionWinnerConfig) => {
  // auctionWinnerConfig value e.g.
  // FencedFrameConfig {
  //   'src': 'opaque' ('ad.com/foo' internally)
  //   ...
  // }
  const adFrame = document.createElement('fencedframe');
  adFrame.config = auctionWinnerConfig;
});

Backwards compatibility

Previously we used a urn:uuid and the src attribute to accomplish this same behavior. We will continue to support urn:uuid and src for a transition period. Update: The src attribute is no longer supported on fenced frames.

Embedder context

After creating the config and prior to loading the config into the fenced frame, an embedder can communicate a string of contextual information to one or more worklets for the Shared Storage API that are spun up inside the fenced frame (details here). This can be useful for reporting purposes.