Bid in an auction to buy an ad slot

As an ad buyer (DSPs and advertisers), you may be interested in participating in a Protected Audience ad auction on the publisher site to target an ad to the interest group you defined on the advertiser site. By participating in Protected Audience auction, you are able to reach your identified customers on other sites in a privacy-preserving way.

In a Protected Audience auction, you provide the logic to generate the bid, and the browser calculates the bid using that logic. This is in contrast to other auction architectures where you submit the bid directly as opposed to providing the logic.

You supply your bid generation logic in the generateBid() JavaScript function and the file is hosted on your server. When you add a user to an interest group, the location of this file is passed into the interest group config as a biddingLogicUrl.

During the auction, the browser fetches your bidding logic specified in the biddingLogicUrl field, and executes your generateBid() function for each interest group in a secure isolated environment that is limited in its communication with outside context. When generateBid() is executed, the browser passes in signals to the function as arguments. These signals contain various information from different sources, such as the publisher's first-party data, seller's data, real-time data, and more. You can use these signals to calculate the bid, and the value is returned from the generateBid() call. After the bids are submitted, the browser will execute the seller's scoring logic on each bid to calculate the seller's desirability score.

generateBid()

The following describes the generateBid() function's arguments and the structure of the bid returned from the function:

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals, directFromSellerSignals) {
  return {
    ad: adObject,
    adCost: optionalAdCost,
    bid: bidValue,
    bidCurrency: 'USD',
    render: {
      url: renderURL,
      width: renderWidth,
      height: renderHeight
    },
    adComponents: [
      {url: adComponent1, width: componentWidth1, height: componentHeight1},
      {url: adComponent2, width: componentWidth2, height: componentHeight2},
      // ...
    ],
    allowComponentAuction: false,
    modelingSignals: 123 // 0-4095 integer (12-bits)
  };
}

Arguments

generateBid() takes the following arguments:

Browser signals

The browserSignals object has the following properties:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://www.top-level-ssp.com',
  requestedSize: {width: 100, height: 200},  /* if specified in auction config */
  joinCount: 3,
  recency: 3600000,
  bidCount: 17,
  prevWinsMs: [[timeDeltaMs1,ad1],[timeDeltaMs2,ad2],...],
  wasmHelper: ...
  dataVersion: 1,
  adComponentsLimit: 40
}

Calculate a bid

To calculate a bid value, code in generateBid() can use the properties of the function's parameters.

For example:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
   //  ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    // ...
  }
}

Return a bid

generateBid() returns an object with the following properties: