Protected Audience API

This initiative was formally known as TURTLEDOVE, then FLEDGE, and now Protected Audiences API (PAAPI). As part of Privacy Sandbox, Chrome proposed this in-browser API that lets advertisers and ad tech companies show interest-group targeted ads without relying on third-party cookies.

Bid requests

Requests may not contain any User Object for website traffic. All other standard fields should be present. The following new extension fields are being used when testing PAAPI.

  • imp.ext.ae int (Optional) Specifies the auction environment.

    • 0 (Default) all on the server-side, i.e traditional auction.

    • 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.

{
  "imp":[
    {
      "ext":{
        "ae":1
      }
    }
  ]
}

Bid responses

Responses must contain the following Interest Group Bid details to be able to participate in an in-browser auction:

  • ext.igbid array of objects (Optional) Interest group bids.

  • ext.igbid.impid string (Required) Refers to the adslot being bid on, the ID should match original request imp.id field.

  • ext.igbid.ignurl - impression notification URL.

  • ext.igbid.igbuyer.origin str (Required) Origin of the Interest Group buyer to participate in the IG auction. Should match the origins where the generateBid() functions are hosted.

  • ext.igbid.igbuyer.buyerdata Any JSON (Optional) Buyer-specific signals used by the buyer’s interest group bidding function. Can be left empty if perBuyerSignals are not required by the buyer bidding function.

  • ext.igbid.igbuyer.seat string (Required) The seat ID of the bidder on whose behalf this bid is made.

  • ext.igbid.igbuyer.maxbid double (Optional) Maximum Interest Group bid price expressed in CPM currency that a bidder agrees to pay if they win an in-browser Interest Group auction expressed expressed in the currency denoted by the cur attribute. Actual winning bid in the in-browser auction that determines the amount a bidder pays for the impression may be lower than this amount. This constraint reduces the risks from in-browser auction bids submitted in error or reported due to fraud and abuse.

  • ext.igbid.igbuyer.cur string (Optional) Indicates the currency in which Interest Group bids will be placed. The maxbid field should always match the cur value. Value must be a three digit ISO 4217 alpha currency code. The default value is USD

  • ext.igbid.igbuyer.ps object (Optional) The buyer’s priority signals, an object mapping string keys to Javascript numbers.

Example PAAPI Ext Response
{
  "ext":{
    "igbid":[
      {
        "impid":"adslot ID",
        "ignurl":"https://example.bidswitch.net/imp_paapi/${AUCTION_PRICE}/_HsPFfA4ea_O5Gpq_0KlrFEZ",
        "igbuyer":[
          {
            "seat":"34"
            "origin":"https://fledge.example.com",
            "buyerdata":{
              "custom_field_1":"value_1"
            },
            "maxbid": 0.75,
            "cur": "USD",
            "ps":{
              "custom_field_3": 1
            }
          },
          {
            "origin":"https://paapi.example.com",
            "buyerdata":{
              "custom_field_2":"value_ABC"
            }
          }
        ]
      }
    ]
  }
}

Impression counting

Impression counting on BidSwitch side is required for multiple areas crucial for trading through BidSwitch, such as:

  • reporting

  • troubleshooting

  • budget and traffic optimization

  • Buyers discrepancy

The most important element in how BidSwitch counts impressions is the ext.igbid.ignurl bid response field. This field contains an impression notification URL sent by BidSwitch in bid response; this URL is to be called by Suppliers upon being notified of an impression. The impression notification URL contains two macros that need to be replaced by the Supplier:

  • ${AUCTION_PRICE}: the clearing price of the Interest Group auction, defined as CPM

Impression Notification URL Example
https://example.bidswitch.net/imp_paapi/${AUCTION_PRICE}/_HsPFfA4ea_O5Gpq_0KlrFEZ

Please refer to the Response Ext Object section for details and response code examples.