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

As part of the [Privacy Sandbox](https://privacysandbox.com/), Chrome proposed the
[Protected Audience
API](https://developer.chrome.com/en/docs/privacy-sandbox/fledge/), 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](https://github.com/WICG/turtledove/blob/main/FLEDGE.md)

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](https://github.com/WICG/turtledove/issues).
- 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](https://developer.chrome.com/blog/announce-enrollment-privacy-sandbox/) 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](https://developers.google.com/static/display-video/protected-audience/images/serving_flow_summary.png)

## Integration options

### Option 1: Direct / Single-seller

![Detailed request flow for single-seller
auctions](https://developers.google.com/static/display-video/protected-audience/images/single_seller_flow.png)

Steps:

1. SSP ad tag sends ad request to SSP server indicating that the browser supports Protected Audience API.
2. SSP server sends contextual OpenRTB bid request to DSP indicating that the browser supports Protected Audience API
3. DSP responds with an OpenRTB bid response containing signals for the on-device auction.
4. SSP server sends ad response with auction configuration to SSP ad tag.
5. SSP ad tag initiates on-device auction by calling [`runAdAuction()`](https://developer.chrome.com/docs/privacy-sandbox/fledge-api/ad-auction/), passing in signals from DSP's openRTB bid response through `perBuyerSignals`.
6. Chrome calls [Key/Value trusted DSP bidding server](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#31-fetching-real-time-data-from-a-trusted-server) to fetch real-time bidding signals.
7. Chrome calls [`generateBid()`](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#32-on-device-bidding) DSP JavaScript function for each participating interest group.
8. Chrome calls [Key/Value trusted SSP scoring server](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#25-additional-trusted-signals-directfromsellersignals) to fetch real-time scoring signals.
9. Chrome calls [`scoreAd()`](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#23-scoring-bids) SSP JavaScript function for each participating interest group.
10. Chrome calls [`reportWin()`](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#52-buyer-reporting-on-render-and-ad-events) DSP JavaScript function to report winner to DSP.
11. Chrome calls [`reportResult()`](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#51-seller-reporting-on-render) 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](https://developers.google.com/static/display-video/protected-audience/images/multi_seller_flow.png)

Steps:

1. SSP adapter sends ad request to SSP server indicating that the browser supports Protected Audience API.
2. SSP server sends contextual OpenRTB bid request to DSP indicating that the browser supports Protected Audience API,
3. DSP server responds with openRTB bid response containing signals for on-device auction.
4. SSP server sends ad response with auction configuration to SSP ad tag.
5. SSP Prebid adapter provides component auction config to Publisher Ad Server tag.
6. Publisher Ad Server tag sends ad request to Publisher Ad Server server.
7. Publisher Ad Server tag initiates on-device auction by calling [`runAdAuction(...)`](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#21-initiating-an-on-device-auction) API.
8. Chrome calls [Key/Value trusted DSP bidding server](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#31-fetching-real-time-data-from-a-trusted-server) to fetch real-time bidding signals.
9. Chrome calls [`generateBid()`](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#32-on-device-bidding) DSP javascript function for each participating interest group.
10. Chrome calls [Key/Value trusted SSP scoring server](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#25-additional-trusted-signals-directfromsellersignals) to fetch real-time scoring signals.
11. Chrome calls [`scoreAd()`](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#23-scoring-bids) SSP JavaScript function for each participating interest group.
12. Chrome calls [`reportWin()`](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#52-buyer-reporting-on-render-and-ad-events) DSP JavaScript function to report winner to DSP.
13. Chrome calls [`reportResult()`](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#51-seller-reporting-on-render) 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](https://docs.prebid.org/dev-docs/modules/fledgeForGpt.html) \* Call Google Ad Manager [ad tag `setConfig()`
    API](https://developers.google.com/publisher-tag/reference#googletag.config.componentauctionconfig) with [multiple
    sellers](https://github.com/google/ads-privacy/tree/master/proposals/fledge-multiple-seller-testing)
- 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`](https://github.com/privacysandbox/fledge-docs/blob/main/bidding_auction_services_api.md).

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`](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#32-on-device-bidding)
about the ad from the `generateBid()` function.

Display \& Video 360 is planning to rely on the following
[`specification`](https://docs.google.com/document/d/1LOfkk2asw1S6NZs0hBAzmU1V8t8GXu_2hfAkSVvn9AM/edit)
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`](https://github.com/WICG/turtledove/blob/main/Fenced_Frames_Ads_Reporting.md).
Even though the name says Fenced Frame Ads Reporting the API is available in
both fenced frames and iframes (see details
[`here`](https://github.com/WICG/turtledove/blob/main/Fenced_Frames_Ads_Reporting.md#support-for-ad-components)).

SSP can register a URL with the browser in their reportResult function by
calling [`registerAdBeacon()`](https://github.com/WICG/turtledove/blob/main/Fenced_Frames_Ads_Reporting.md#registeradbeacon)
API.

Display \& Video 360 will call [`reportEvent()`](https://github.com/WICG/turtledove/blob/main/Fenced_Frames_Ads_Reporting.md#reportevent-preregistered-destination-url)
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`](https://developer.chrome.com/docs/privacy-sandbox/chrome-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`](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/deprecation_test_label.md):

**Object: Device.ext**

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

## Related documents

- [Protected Audience API on Chrome Developers](https://developer.chrome.com/en/docs/privacy-sandbox/fledge/)
- [First Experiment on GitHub](https://github.com/WICG/turtledove/blob/main/FLEDGE.md)