Seller API guide and references for the Protected Audience API ad auction.
In this article, you'll find a technical reference for the ad auction, as used in the current iteration of the experimental Protected Audience API.
Read the developer guide for the full life cycle of Protected Audience API, and refer to the Protected Audience API explainer for an in-depth discussion of how sellers run on-device auctions.
Not a developer? Refer to the Protected Audience API overview.
What is the Protected Audience API ad auction?
A Protected Audience API ad auction is a collection of small JavaScript programs the browser runs on the user's device to choose an ad. To preserve privacy, all ad auction code from the seller and buyers is run in isolated JavaScript worklets that can't talk to the outside world.
- A user visits a site which displays ads.
- The seller's code executes
navigator.runAdAuction()
. This specifies which ad space is for sale and who can bid. Sellers must also include a script that scores each bid,scoreAd()
. - The invited buyer's code executes to generate a bid, URL for a relevant ad creative, and other data. The bidding script can query for real-time data, such as the remaining ad campaign budget, from the buyer's Key/Value service.
- The seller's code scores each bid and selects a winner. This logic uses the bid value and other data return a bid's desirability. Ads which cannot beat the contextual winner are rejected. The seller can use their own Key/Value service for real-time data.
- The winning ad is returned as an opaque value, which displays in a fenced frame. Both the seller and publisher will be unable to view this value.
- The auction is reported to the seller and winning buyers.
When does the auction take place?
The Protected Audience API can be run on its own or with programmatic auctions. In a multi-seller, programmatic auction:
- The user visits a participating site.
- A programmatic auction is run by another seller to find a contextual ad for an available ad slot.
- The Protected Audience API auction is run.
scoreAd()
compares the buyer's bids with the results of the first auction.
Bids which cannot beat the contextual winner are rejected.
Who runs the Protected Audience API ad auction?
There are multiple parties that might run an auction to sell ad space.
For example:
- Content publisher: acting for itself to host ad content on its website.
- Supply-side platform (SSP): working with the publisher and providing other services.
- Third-party script: acting for a publisher, to enable participation in ad auctions.
With the Protected Audience API, a seller has three jobs:
- Enforce publisher rules: which buyers and which bids are eligible.
- Run auction logic: JavaScript run in worklets to calculate a desirability score for each bid.
- Report the auction outcome.
These jobs are done programmatically, in code provided by the seller when it
instigates an ad auction by calling the JavaScript function
navigator.runAdAuction()
.
API functions
runAdAuction()
The seller makes a request to the user's browser to begin an ad auction by calling navigator.runAdAuction()
.
For example:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction()
returns a promise that resolves to a URN (urn:uuid:<something>
) that represents the
ad auction outcome. This can only be decoded by the browser when passed to a fenced frame
for rendering: the publisher page cannot inspect the winning ad.
The decisionLogicUrl
script considers each individual ad, along with its
associated bid and metadata, one at a time, and then assigns it a numerical
desirability score.
auctionConfig
properties
seller
- Required
- Example:
'https://ssp.example'
- Role: Origin of the seller.
decisionLogicUrl
- Required
- Example:
'https://ssp.example/auction-decision-logic.js'
- Role: URL for auction worklet JavaScript.
trustedScoringSignalsUrl
- Optional
- Example:
'https://ssp.example/scoring-signals'
- Role: URL of seller's trusted server.
interestGroupBuyers
- Required
- Example:
['https://dsp.example', 'https://buyer2.example', ...]
- Role: Origins of all interest group owners asked to bid in the auction.
- Notes: The seller may specify
interestGroupBuyers:
to permit all interest groups to bid. Ads are then accepted or rejected based on criteria other than inclusion of the interest group owner. For example, the seller may review ad creatives to confirm compliance with their policies. auctionSignals
- Optional
- Example:
{...}
- Role: Seller information about page context, type of auction, etc.
sellerSignals
- Optional
- Example:
{...}
- Role: Information based on publisher settings, making a contextual ad request, etc.
sellerTimeout
- Optional
- Example:
100
- Role: Maximum runtime (ms) of seller's
scoreAd()
script. perBuyerSignals
- Optional
- Example:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
- Role: Contextual signals about the page for each specific buyer, from their server.
perBuyerTimeouts
- Optional
- Example:
50
- Role: Maximum runtime (ms) of particular buyer's
generateBid()
scripts. componentAuctions
- Optional
- Example:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
- Role: Additional configurations for component auctions.
decisionLogicUrl
The decisionLogicUrl
is a property of the auction configuration object,
passed to runAdAuction()
. This URL must include a script for the
scoreAd()
function. This logic is run once for each ad to
determine its desirability.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals
is an object constructed by the browser, including information
that the browser knows and which the seller's auction script might want to
verify:
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}
Before an auction starts, the seller finds the best contextual ad for the
available ad slot. Part of the scoreAd()
logic rejects any ad that can't
beat the contextual winner.
scoreAd()
scoreAd()
takes the following arguments:
Argument | Role |
---|---|
adMetadata |
Arbitrary metadata provided by the buyer. |
auctionConfig |
The auction configuration object passed to navigator.runAdAuction() . |
bid |
A numerical bid value. |
trustedScoringSignals |
Values retrieved at auction time from the seller's trusted server, representing the seller's opinion of the ad. |
Frequently asked questions
How is the auction winner decided and who picks them?
The seller provides the scoring logic to determine the desirability score of each ad, and the browser selects the highest score as the winning ad.
The seller includes logic in the scoreAd()
function, and the browser executes the function in a worklet that has limited communication with code outside of it. The browser itself does not score the ads. The browser is exclusively responsible to execute the scoring logic and select the bid with the highest score.
All Protected Audience API references
API reference guides are available:
- Developer guide for the Protected Audience API.
- Ad buyer guide to Protected Audience interest groups and bid generation.
- Ad seller guide to Protected Audience ad auctions.
- Guide to reporting auction results
- Best practices for Protected Audience ad auction latency
- Troubleshoot Protected Audience
The Protected Audience API explainer also provides detail about feature support and constraints.