Seller guide: run ad auctions

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.

Six stages in a Protected Audience API ad auction
This diagram outlines each stage of a Protected Audience API ad auction.
  1. A user visits a site which displays ads.
  2. 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().
  3. 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.
  4. 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.
  5. 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.
  6. 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:

  1. The user visits a participating site.
  2. A programmatic auction is run by another seller to find a contextual ad for an available ad slot.
  3. The Protected Audience API auction is run.
  4. 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:

The Protected Audience API explainer also provides detail about feature support and constraints.