multi-piece-ad

Ads Composed of Multiple Pieces

Overview

Overview

Description

Advertisers can display multiple products/pieces in one ad unit, allowing users to click directly to individual product pages. This is achieved through a template 'container' with customizable product slots.

Privacy Sandbox APIs

• Protected Audience API

Related parties

• SSP
• Advertiser
• DSP

Design

Design

Goals

In this demo, the auction setup and execution is similar to the sequential setup of Protected Audience with contextual ad auction demo. So, please check this use case implementation first if you want to learn about the Protected Audience auction setup.

The only incremental difference in this use-case is that the advertiser can provide more than one product that the user interacted with in the same ad slot.

Assumptions​

This use case assumes the advertiser (shop site) can bid on the publisher (news site) inventory through an agreement between their respective DSP and SSP platforms.

We use "MULTIPIECE" as a new ad request type for demonstration purposes, but in real life applications, such a signal to communicate the support for a multi-piece ad may not be required.

System Design

Using Protected Audience API, the user visits a product in the shopping site, and gets added to an interest group. This interest group can include a list of products that this user has interacted with, which can be tracked using first-party data. This list will be stored in the adComponents field of the interest group object.

Later the same user visits a news site. There, the browser runs an on-device auction with the Protected Audience API, and the ad seller’s scoring logic will select the winning ad which will be dynamically rendered on the publisher page.

Demo

Demo

Prerequisites

• Latest stable version of Chrome (Open chrome://version to check your current version)
• Enable Privacy Sandbox APIs (Open chrome://settings/adPrivacy to enable Site-suggested ads and Ad measurement)
• Clear your browsing history before you run one of the demo scenario below (Open chrome://settings/clearBrowserData to delete your browsing history)

User Journey

1. Navigate to shop site (Advertiser)
2. Click on a “shoe” product item on the shop site.
   • The shop (advertiser) would assume the user is interested in this type of product, so they would leverage Protected Audience API and ask the browser to join an ad interest group for this product or this specific product category.
3. Navigate to news site (Publisher)
4. Observe the ad served on the news site. The shoe that you previously browsed will be shown between other 4 shoes in a multi-piece ad.

Implementation details

How is the product browsed added to an Interest Group?

To implement the multi-piece ad, the user joins the interest group which contains one ad in the ads field and also contains a list of products/ads in the adComponents field.

The top-level ad ("container") includes some slots that can be filled in with specific products ("ad components").

The adComponents field contains the various ad components that can be used to construct "ads composed of multiple pieces". Similar to the ads field, each entry is an object that includes a renderURL, optional adRenderId, and metadata fields.

const myGroup = {
  'owner': 'https://www.example-dsp.com',
  'name': 'womens-running-shoes',
  'ads': [
    {renderUrl: "container.html", sizeGroup: 'group1', ...},
    {renderUrl: shoesAd2, sizeGroup: 'group2'},
  ],
  'adComponents': [
    {renderUrl: runningShoes1, sizeGroup: 'group2', ...},
    {renderUrl: runningShoes2, sizeGroup: 'group2', ...},
    {renderUrl: gymShoes, sizeGroup: 'group2', ...},
  ],
  'adSizes': {
    'size1': {width: '100', height: '100'},
    'size2': {width: '100', height: '200'},
    'size3': {width: '75', height: '25'},
    'size4': {width: '100', height: '25'},
  },
  'sizeGroups:' {
    'group1': ['size1', 'size2', 'size3'],
    'group2': ['size3', 'size4'],
  },
  ...
};

The adSizes field contains a dictionary of named ad sizes. Each size has the format {width: widthVal, height: heightVal}, where the values can have either pixel units (e.g. 100 or 100px) or screen dimension coordinates (e.g. 100sw or 100sh).

The sizeGroups field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at.

How do we serve a Multi Piece Ad?

If the bid returns a multi piece ad, the creative's URL ("container") must match the renderURL of an ad in the interest group's ads list. Additionally, the bid also needs to return the adComponents field with the selected products for this creative, where each value must match one of adComponents, renderURL and sizeGroup included in the interest group.

Importantly, the adComponents returned in the bid don't have to include every item from the interest group's adComponents, giving ad-techs the flexibility to choose which ads or products to display.

const bid = {
  ...,
  'bid': bidValue,
  'bidCurrency': 'USD',
  'render': {
    'url': 'https://www.example.com/ads/multi-piece-container.html',
    'width': renderWidth,
    'height': renderHeight
  },
  'adComponents': [
    {
      'url': 'https://www.example.com/ads/multi-piece-product1.html',
      'width': componentWidth1,
      'height': componentHeight1
    },
    {
      'url': 'https://www.example.com/ads/multi-piece-product1.html',
      'width': componentWidth2,
      'height': componentHeight2
    },
    ...
  ],
}

To serve ads from adComponents, you can utilize either iframes or Fenced Frames. Ad-techs may either use the navigator.adAuctionComponents(numberOfAdComponents) function which provides an array containing the requested number of adComponents along with their respective renderURL, or the window.fence.getNestedConfigs() method to retrieve an array of FencedFrameConfigs that can be rendered in Fenced Frames.

Related API documentation

• Ads Composed of Multiple Pieces
• Protected Audience API overview