Learn how to configure a Protected Audience API auction.
On-device auctions run by sellers
An on-device Protected Audience auction runs on a site selling ad spaces, and we refer to the party running the auction as the seller. Many parties might act as sellers: a site might run its own ad auction, or might include a third-party script to run the auction for it, or might use an SSP that combines running an on-device auction with other server-side ad auction activities. Sellers have three basic jobs in the on-device ad auction:
- Sellers decide (a) which buyers may participate, and (b) which of the bids from those buyers' interest groups are eligible to enter the auction. This lets the seller enforce the site's rules for what ads are allowed to appear on the page.
- Sellers are responsible for the business logic of the auction: JavaScript code which considers each bid's price and metadata, and calculates a "desirability" score. The bid with the highest desirability score wins the auction.
- Sellers perform reporting on the auction outcome, including information about clearing price and any other pay-outs. The winning and losing buyers also get to do their own reporting.
This document will explain how to configure and initiate an on-device auction.
Configure a Protected Audience API ad auction
In order to run a Protected Audience API ad auction, the first step is to
configure the auction. This is done by creating an auctionConfig
object.
Here is an example of one such configuration:
const auctionConfig = {
seller: 'https://seller.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://buyer-1.example': {...},
'https://buyer-2.example': {...},
...
},
perBuyerTimeouts: {
'https://buyer-1.example': 50,
'https://buyer-2.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://component-seller.example',
'decisionLogicUrl': ...,
...
},
...
],
resolveToConfig: [true|false],
};
AuctionConfig
properties
Required properties
The only required properties for auctionConfigs
are the seller
,
decisionLogicUrl
, and interestGroupBuyers
.
Property | Example | Role |
---|---|---|
seller | https://seller.example | Origin of the seller. |
decisionLogicUrl | https://seller.example/decision-logic.js | URL for auction JavaScript decision logic worklet. This field needs to have the same origin as the seller field. |
interestGroupBuyers | [https://buyer-1.example, https://buyer-2.example, ...] |
Origins of all interest group owners asked to bid in the auction |
Optional properties
The remaining properties for auctionConfigs
are optional.
Property | Example | Role |
---|---|---|
trustedScoringSignalsUrl | https://seller.example/scoring-signals | URL of seller's Key/Value server. This will be queried during the ad scoring process using the render URL of the creative as the key. This field needs to have the same origin as the seller field. |
auctionSignals | {"category":"news"} | JSON serializable object representing the signals available to all buyers and sellers participating in the auction. |
sellerSignals | {...} | JSON serializable object representing signals available to only the sellers. |
perBuyerSignals | {https://dsp.example: {...}, https://another-buyer.example: {...}, ... } |
Signals available to a specific buyer. The signals can come from the sellers and also by the buyers themselves. |
perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...}, |
Maximum runtime in milliseconds of a particular buyer's generateBid() script. A wildcard symbol will be applied to every buyer that does not have a specific timeout defined. |
sellerTimeout | 100 | Maximum runtime in milliseconds of a seller's scoreAd() script. |
componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | Additional configurations for component auctions. |
resolveToConfig | true|false | A boolean directing the promise returned from runAdAuction() to resolve to a FencedFrameConfig if true (for use in a <fencedframe>), or to an opaque urn:uuid URL if false (for use in an <iframe>). Defaults to false. |
Provide signals asynchronously
The values of some signals (those configured by auctionSignals
,
sellerSignals
, perBuyerSignals
, and perBuyerTimeouts
fields) can
optionally be provided not as concrete values, but as Promises. This permits
some parts of the auction, such as loading of scripts and trusted signals, and
launching of isolated worklet processes, to overlap the computation (or network
retrieval) of those values. The worklet scripts will only see the resolved
values; if any such Promise is rejected, the auction will be aborted unless it
managed to fail already or get aborted in other ways.
Configure an auction with multiple sellers
In some cases, multiple sellers may want to participate in an auction, with the
winners of separate auctions being passed up to another auction, run by another
seller. These separate auctions being passed up are called component auctions.
To facilitate these component auctions, componentAuctions
object can contain
additional auction configurations for each seller's component auction. The
winning bid of each of these component auctions will be passed to the
"top-level" auction which makes the final determination of the auction. The
auctionConfig
of component auctions may not have their own
componentAuctions
. When componentAuctions
is non-empty,
interestGroupBuyers
must be empty. That is, for any particular Protected
Audience auction, either there is a single seller and no component auctions, or
else all bids come from component auctions and the top-level auction can only
choose among the component auctions' winners.
Run the auction
The seller makes a request to the user's browser to begin an ad auction by
calling navigator.runAdAuction()
.
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
The runAdAuction()
call returns a Promise that resolves to the ad. It is not
possible for any code on the publisher page to inspect the winning ad or
otherwise learn about its contents from the result of runAdAuction()
. If the
resolveToConfig
flag was set to true in the AuctionConfig
, a
FencedFrameConfig
object is returned which can only be rendered in a fenced
frame. If the flag was set to false, then an opaque URN is returned which can be
rendered in an iframe. It is possible that runAdAuction returns a null value,
indicating that no ad was selected. In this case the seller might choose to
render a contextually targeted ad.