Protected Audience (formerly known as FLEDGE) Integration and Testing Guide for SSPs

As part of the Privacy Sandbox, Chrome proposed the Protected Audience API, an in-browser API that lets advertisers and ad tech companies to curate and target interest groups (audience lists) without relying on third-party cookies, while protecting users from cross-site tracking. Developer guide

SSPs can test Protected Audience API with Display & Video 360 and Google Ads to:

Iterate on and learn about the efficacy of Protected Audience API flows.
Propose and generate feedback on potential API improvements in public forums—for example, GitHub.
Prepare for supporting personalized advertising through Protected Audience API without relying on third-party cookies.

The following guide describes integration details between an SSP and Display & Video 360 and Google Ads. SSPs interested in coordinating a test should get in contact with their Display & Video 360 Partnership representative.

Enrollment

SSPs should register themselves to use the Protected Audience API.

Serving flow summary

The following diagram shows the generic flow outlining the main interaction points between Chrome, SSP, Display & Video 360 and Google Ads.

Sequence diagram showing requests between Chrome, SSP and
DSP

Integration options

Option 1: Direct / Single-seller

Detailed request flow for single-seller
auctions

Steps:

SSP ad tag sends ad request to SSP server indicating that the browser supports Protected Audience API.
SSP server sends contextual OpenRTB bid request to DSP indicating that the browser supports Protected Audience API
DSP responds with an OpenRTB bid response containing signals for the on-device auction.
SSP server sends ad response with auction configuration to SSP ad tag.
SSP ad tag initiates on-device auction by calling runAdAuction(), passing in signals from DSP's openRTB bid response through perBuyerSignals.
Chrome calls Key/Value trusted DSP bidding server to fetch real-time bidding signals.
Chrome calls generateBid() DSP JavaScript function for each participating interest group.
Chrome calls Key/Value trusted SSP scoring server to fetch real-time scoring signals.
Chrome calls scoreAd() SSP JavaScript function for each participating interest group.
Chrome calls reportWin() DSP JavaScript function to report winner to DSP.
Chrome calls reportResult() SSP JavaScript function to report winner to SSP.

Minimum changes on the SSP side

SSP ad tag needs to be updated to
- detect whether browser supports Protected Audience API
- send that information as part of the ad request to SSP server [1]
- initiate an on-device auction by calling runAdAuction() passing in signals from DSP's OpenRTB bid response [5] (see buyerdata field on bid request and response structure below).
SSP server needs to
- propagate information about Protected Audience API support to DSP through the field in the OpenRTB bid request [2] (see section on bid request and response structure below).
- propagate DSP's buyer signals in the OpenRTB bid response to the SSP ad tag (see section on bid request / bid response structure below) [4]
[Optional] SSP needs to implement Trusted SSP server to fetch realtime scoring signals to support ad quality checks, publisher settings enforcement [8]
SSP needs to implement javascript with "scoreAd(...)" and "reportResult(...)" functions [9], [11]

Option 2: Multi-seller

Detailed request flow for multi-seller auctions

Steps:

SSP adapter sends ad request to SSP server indicating that the browser supports Protected Audience API.
SSP server sends contextual OpenRTB bid request to DSP indicating that the browser supports Protected Audience API,
DSP server responds with openRTB bid response containing signals for on-device auction.
SSP server sends ad response with auction configuration to SSP ad tag.
SSP Prebid adapter provides component auction config to Publisher Ad Server tag.
Publisher Ad Server tag sends ad request to Publisher Ad Server server.
Publisher Ad Server tag initiates on-device auction by calling runAdAuction(...) API.
Chrome calls Key/Value trusted DSP bidding server to fetch real-time bidding signals.
Chrome calls generateBid() DSP javascript function for each participating interest group.
Chrome calls Key/Value trusted SSP scoring server to fetch real-time scoring signals.
Chrome calls scoreAd() SSP JavaScript function for each participating interest group.
Chrome calls reportWin() DSP JavaScript function to report winner to DSP.
Chrome calls reportResult() SSP JavaScript function to report winner to SSP.

Minimum changes on the SSP side

SSP adapter needs to be updated to
- detect whether browser supports Protected Audience
- send that information as part of the ad request to SSP server [1]
- provide component auction config to Publisher Ad Server ad tag [5].
- If Google Ad Manager is the publisher ad server, then SSP can either * Use prebid Protected Audience module * Call Google Ad Manager ad tag setConfig() API with multiple sellers
SSP server needs to
- propagate information about Protected Audience support to DSP through the field in the OpenRTB bid request [2] (see section on bid request and response structure below).
- propagate DSP's buyer signals in the OpenRTB bid response to the SSP ad tag (see section on bid request / bid response structure below) [4]
[Optional] SSP needs to implement Trusted SSP server to fetch realtime scoring signals to support ad quality checks, publisher settings enforcement [10]
SSP needs to expose JavaScript with scoreAd() and reportResult() functions [11], [14].

Bidding and Auction Services

We are closely evaluating the Bidding & Auction Services (B&A) proposal.

When Display & Video 360 is ready to test the Protected Audience API with B&A, we will reach out with more details.

OpenRTB protocol

Bid request

To differentiate between impression opportunities that support Protected Audience API on-device auction from those that only support standard server-side exchange auction, a new enum field called ae for "auction environment" should be added as an extension to the Imp object in the OpenRTB bid request to specify which auction environment is supported by the given impression slot. The ae enum can have the following values:

0: Standard server-side auctions
1: Requests with Protected Audience API support, in which a contextual auction runs on the exchange's servers and the interest group bidding and the final auction runs in the browser

{
  "id": …
  "imp": [{
    "id": "1"
    "video": {...}
    "ext": {
      "ae": 1
    }]
}

Bid response

In addition to the contextual bids, a bid response is also used to pass information relevant to Display & Video 360 and Google Ads participation in the Protected Audience API interest group auctions. The bid response is updated to support the interest group auctions as follows:

{
  "seatbid": [{
    "bid": [{
      … // Traditional contextual bids
    }]
  }],

  "ext": {
    // InterestGroupBidding object which holds information for running an
    // in-browser interest group auction.
    "igbid": [{
      // ID of the Imp object of the impression to which
      // these interest group bidding signals apply to.
      "impid": "1",

      // InterestGroupBuyer object which holds DSP information for the in-browser
      // auction.
      "igbuyer": [{
        // Origin of Display & Video 360 and Google Ads to participate in the
        // interest group auction. For more info regarding the origin see:
        // https://developer.mozilla.org/en-US/docs/Glossary/Origin
        "origin": "https://td.doubleclick.net",

        // Buyer-specific signals to use in auctionConfig as perBuyerSignals.
        // Used by the buyer's interest group bidding function. Can be left empty
        "buyerdata": ...,

        // Buyer experiment group id to support coordinated experiments with
        // buyers' trusted servers. This experiment id should be added to the
        // `perBuyerExperimentGroupIds` map in auctionConfig.
        "buyer_experiment_group_id": 12345
      }]
    }]
  }
}

The following scenarios are supported.

SCENARIO 1: Display & Video 360 and Google Ads only wants to participate in a contextual auction. In this scenario there is no igbid field present.
SCENARIO 2: Display & Video 360 and Google Ads only wants to participate in an interest group auction. In this scenario Display & Video 360 and Google Ads will drop the seatbid field in the bid response and will only return igbid information. In other words, presence of igbid field indicates the fact that Display & Video 360 and Google Ads wants its interest groups to participate in the on-device auction.
SCENARIO 3: Display & Video 360 and Google Ads wants to participate in both contextual and interest group auctions. In this scenario Display & Video 360 and Google Ads will return both seatbid field in the bid response and igbid information.

Metadata with Ad Bid

Protected Audience API allows passing arbitrary metadata about the ad from the generateBid() function.

Display & Video 360 is planning to rely on the following specification for the ad metadata: Protected Audience API and OpenRTB.

Namely Display & Video 360 will return the following fields as part of the ad object:

PA Attribute	Type	OpenRTB Description
ad.seat	String; required	ID of the buyer seat (e.g., advertiser, agency) on whose behalf this bid is made.
ad.adomain	String[]	Advertiser domain for block list checking (e.g., "ford.com"). This can be an array of for the case of rotating creatives. Exchanges can mandate that only one domain is allowed.
ad.cid	string	Campaign ID to assist with ad quality checking.
ad.crid	string	Creative ID to assist with ad quality checking.
ad.language	string	Language of the creative using ISO-639-1-alpha-2. The non- standard code "xx" may also be used if the creative has no linguistic content (e.g., a banner with just a company logo). Only one of language or langb should be present.
ad.w	integer	Width of the creative in device independent pixels (DIPS).
ad.h	integer	Height of the creative in device independent pixels (DIPS).

Example

{
  "seat": "123"
  "adomain": ["example.com"]
  "cid": "12345"
  "crid": "12345"
  "language": "en"
  "w": 300
  "h": 250
}

Event Reporting

Protected Audience API provides an event-level reporting API described in this GitHub post: Fenced Frame Ads Reporting. Even though the name says Fenced Frame Ads Reporting the API is available in both fenced frames and iframes (see details here).

SSP can register a URL with the browser in their reportResult function by calling registerAdBeacon() API.

Display & Video 360 will call reportEvent() API with the destination 'component-seller' from within the creative to report impressions and click events. That will result in a beacon being sent to the registered URL.

Note that Display & Video 360 will call reportEvent() API for impressions and clicks with empty post data.

Example

registerAdBeacon({
 'impression': 'https://ssp.example/impression?ssp_event_id=abc',
});
registerAdBeacon({
 'click': 'https://ssp.example/click?ssp_event_id=abc',
});

Cookie deprecation test label

Display & Video 360 is going to participate in Chrome-facilitated testing of third-party cookie deprecation. To be able to do the testing we ask partners to pass us the Chrome labels in OpenRTB bid request according the following specification:

Object: Device.ext

Attribute	Type	Description
cdep	String	the label as received from Chrome or an upstream partner.

Protected Audience (formerly known as FLEDGE) Integration and Testing Guide for SSPs

Enrollment

Serving flow summary

Integration options

Option 1: Direct / Single-seller

Minimum changes on the SSP side

Option 2: Multi-seller

Minimum changes on the SSP side

Bidding and Auction Services

OpenRTB protocol

Bid request

Bid response

Metadata with Ad Bid

Event Reporting

Cookie deprecation test label

Related documents