Set up an ad auction on the publisher's page

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:

1. 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.
2. 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.
3. 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

Note: additionalBids is not supported in the current implementation of the Protected Audience API. Read the Auction Participants section in the Protected Audience API explainer for more information.

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.