Render an ad

When a Protected Audience auction returns an ad candidate, it can either be returned as an opaque URN, which is used to render an ad in an iframe, or a FencedFrameConfig which is used to render the ad in a fenced frame.

This guide will explain what a fenced frame is and why it is needed, as well as how to render an ad using either method. For a more in-depth look at fenced frames, find more information in this guide or in the proposal.

What are fenced frames?

A fenced frame (<fencedframe>) is an HTML element for embedded content, similar to an iframe. Unlike iframes, a fenced frame restricts communication with its embedding context to allow the frame access to cross-site data without sharing it with the embedding context. Similarly, any first-party data in the embedding context cannot be shared with the fenced frame.

For example, say news.example (the embedding context) embeds an ad from shoes.example in a fenced frame. news.example cannot exfiltrate data from the shoes.example ad, and shoes.example cannot learn first-party data from news.example.

How do fenced frames work?

Fenced frames use the FencedFrameConfig object for navigation. This object can be returned from a Protected Audience auction. Then, the config object is set as the config attribute on the fenced frame element. This differs from an iframe where a URL or opaque URN is assigned to the src attribute. The FencedFrameConfig object has a read-only url property; however, since the current use-cases require the actual URL of the internal resource to be hidden, this property returns the string opaque when read.

A fenced frame can't use postMessage to communicate with its embedder. However, a fenced frame can use postMessage with iframes inside the fenced frame.

Fenced frames will be isolated from the publisher in other ways. The publisher won't have access to the DOM inside of a fenced frame, and the fenced frame cannot access the publisher's DOM. Further, attributes such as name, which can be set to any value to and observed by the publisher, aren't available in fenced frames.

Fenced frames behave like a top-level browsing context (such as a browser tab). Although a fenced frame in certain use cases (such as opaque-ads) can contain cross-site data (such as a Protected Audience API interest group), the frame cannot access unpartitioned storage or cookies. An opaque-ads fenced frame can access a unique, nonce-based cookie and storage partition.

The characteristics of fenced frames are further detailed in the explainer.

Render an ad in a fenced frame

A FencedFrameConfig is returned from a Protected Audience auction, provided that the AuctionConfigs resolveToConfig parameter was set to true:

const frameConfig = await navigator.runAdAuction({
  // ...auction configuration
  resolveToConfig: true
});

Once you have obtained the config, you can assign it to a fenced frame's config attribute to navigate the frame to the resource represented by the config. Earlier versions of Chrome don't support the resolveToConfig property, so you must still confirm that the promise resolved to aFencedFrameConfig before navigating:

if (window.FencedFrameConfig && frameConfig instanceof FencedFrameConfig) {
  const frame = document.createElement('fencedframe');
  frame.config = frameConfig;
}

Render an ad in an iframe

If the AuctionConfig does not explicitly set resolveToConfig or if it is set to false, runAdAuction() returns an opaque URN. This URN can be set as an iframe's src to render the ad.