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:

Argument	Role
`interestGroup`	An object passed to by the ad buyer. The interest group may be updated with `dailyUpdateUrl` .
`auctionSignals`	A property of the auction config argument passed to `navigator.runAdAuction()` by the seller. This provides information about page context (such as the ad size and the publisher ID), the type of auction (first-price or second-price), and other metadata.
`perBuyerSignals`	A property of the auction config argument passed by the seller. This can provide contextual signals from the buyer's server about the page, if the seller is an SSP which performs a real-time bidding call to buyer servers and pipes the response back, or if the publisher page contacts the buyer's server directly. If so, the buyer may want to check a cryptographic signature of those signals inside `generateBid()` as protection against tampering.
`trustedBiddingSignals`	An object whose keys are the `trustedBiddingSignalsKeys` for the interest group, and whose values are returned in the `trustedBiddingSignals` request.
`browserSignals`	An object constructed by the browser, which might include information about page context (such as the `hostname` of the current page, which the seller could otherwise fake) and data for the interest group itself (such as a record of when the group previously won an auction, to allow on-device frequency capping).
`directFromSellerSignals`	Signals that come from a specific seller, unlike `auctionSignals` and `sellerSignals` that can come from any participant that's present in the context of where `runAdAuction` is executed.

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
}

Property	Description
`topWindowHostname`	The hostname of where the `runAdAuction()` call was made.
`seller`	The seller that the bid is submitted to. In a component auction, this value is the component seller.
`topLevelSeller`	The top-level seller in a component auction, and is only present in a component auction.
`requestedSize`	The `requestedSize` property recommends a frame size for the auction. The seller sets the requested size in the auction config, and the value becomes available to bidders in `generateBid()` . Bidders inside the auction may pick a different content size for the ad, and that resulting size will be visually scaled to fit inside the element's container size.
`joinCount`	The `joinCount` field is the number of times this device has joined this interest group in the last 30 days while the interest group has been continuously stored (that is, there are no gaps in the storage of the interest group on the device due to leaving or membership expiring).
`recency`	The `recency` field is duration of time (in minutes) from when this device joined this interest group until now
`bidCount`	The number of times that interest group has submitted a bid.
`prevWinsMs`	The `prevWinMs` field contains the interest group's winning ads, and the time since their previous wins in milliseconds. Note that the ad object here only contains the `renderURL` and metadata fields.
`wasmHelper`	a WebAssembly.Module object based on interest group's `biddingWasmHelperURL` .
`dataVersion`	Data-Version value from the buyer's Key/Value service response(s).
`adComponentsLimit`	Maximum number of ad components `generateBid()` may return

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:

Property

Role

ad

Arbitrary metadata about the ad, such as information the seller expects to learn about this bid or ad creative. The seller uses this information in its auction and decision logic.

adCost

A numerical value used to pass reporting advertiser click or conversion cost from generateBid to reportWin. The precision of this number is limited to an 8-bit mantissa and 8-bit exponent, with any rounding performed stochastically.

adComponents

An optional list of up to 20 components for ads composed of multiple pieces , taken from the adComponents property of the interest group argument passed to navigator.joinAdInterestGroup() .

allowComponentAuction

A boolean value indicating whether this bid can be used in a component auction. Defaults to "false" if not specified.

bid

A numerical bid that will enter the auction. The seller must be in a position to compare bids from different buyers, therefore bids must be in some seller-chosen unit (such as"USD per thousand"). If the bid is zero or negative, then this interest group won't participate in the seller's auction at all. With this mechanism, the buyer can implement any advertiser rules for where their ads may or may not appear.

bidCurrency

The currency for the bid, used for currency-checking .

render

A dictionary describing the creative that should be rendered if this bid wins the auction. This includes:

url : The creative's URL.

width : The creative's width. This size will be matched against the declaration in the interest group and substituted into any ad size macros present in the ad creative URL. When the ad is loaded in a fenced frame, the fenced frame's inner frame (i.e. the size visible to the ad creative) will be frozen to this size, and it will be unable to see changes to the frame size made by the embedder.

height : The creative's height. See elaboration in width .

modelingSignals

A 0-4095 integer (12-bits) passed to reportWin() , with noising, as described in the noising and bucketing scheme . Invalid values, such as negative, infinite, and NaN values, will be ignored and not passed. Only the lowest 12 bits will be passed.

The buyer can use the signals available inside the generateBid() function, including data from first-party buyer data captured at Interest Group creation time in userBiddingSignals , to derive some value that is passed to the buyer's win reporting function to enable ML model training.