Run a browser based auction with a single seller

In this document, you'll find a high-level overview for running an auction with Protected Audience data for a single seller, as used in the current iteration of the Protected Audience API. An auction with a single seller can be executed as part of a more complex auction involving multiple sellers. In this case, the single seller auction is referred to as a "component auction", which can provide ad candidates to the "top level auction" that has multiple sellers participating.

Read the developer guide for the full lifecycle of Protected Audience API, and refer to the Protected Audience API explainer for an in-depth discussion of how sellers run on-device auctions.

Six stages of 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.

An auction can take place when a user navigates to a page that displays an ad. Auctions may be run ahead of time so that the ad creative is ready when the ad slot comes into view.

Sellers initiate the ad auction, score candidate ads using custom logic provided as a scoreAd() function, and are responsible for reporting the results of the auction to themselves as well as the winning buyer. Sellers are also able to enforce publisher rules and filter for ad quality using their scoreAd() function.

A seller may refer to:

• Content publishers, acting for itself to host ad content on its website
• Supply-side platforms (SSPs), working with the ad publisher and providing other services
• Third-party scripts, acting for a publishers to enable participation in ad auctions.

Prerequisites for running an auction

A seller needs two JavaScript functions defined to run an auction:

• scoreAd(), which scores an ad candidate
• reportResult(), which handles reporting the result of the auction to the seller themselves

These scripts need to be served from a single endpoint the seller owns.

scoreAd()

A seller needs to define a scoreAd() function that is served from an endpoint that they own. The endpoint is specified in the auction configuration as the decisionLogicUrl. The scoreAd() function has the following signature:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

The scoreAd() parameters are:

• adMetaData, which is arbitrary metadata about the ad creative that is provided by the buyer. This is a JSON serializable object that sellers and buyers will need to define and agree on the structure.
• bid, which is a numerical value representing the bid.
• auctionConfig, which is the auction configuration used to execute the auction.
• trustedScoringSignals, which are signals read at auction time from the seller's Key/Value server. The platform will use the renderUrl of the candidate ad as the key for this lookup.
• browserSignals, which is an object constructed by the browser, including information that the browser knows and which the seller's auction script might want to verify.
• directFromSellerSignals is an object that may contain the following fields: ** sellerSignals: Like auctionConfig.sellerSignals, but passed using the directFromSellerSignals mechanism. ** auctionSignals: Like auctionConfig.auctionSignals, but passed using the directFromSellerSignals mechanism.

The following is an example of browserSignals. Note that the renderUrl of the candidate ad is available through these signals:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

A seller needs to define a reportResult() function that is served from an endpoint that they own. The endpoint is specified in the auction configuration as the decisionLogicUrl. The reportResult() function has the following signature:

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

The reportResult() parameters are:

• auctionConfig, which is the auction configuration used to execute the auction.
• browserSignals, which is an object constructed by the browser, including information that the browser knows and which the seller's auction script might want to verify. This is the same object passed to the scoreAds() function.

reportResult() returns signalsForWinner, which is an arbitrary JSON object that is passed to the winning buyer's reporting function. This should include any relevant information the seller can provide about the auction that the buyer requires for their reporting.

Run a Protected Audience API auction

There are four main steps a seller must take to run an auction. Note that these steps assume the seller has an endpoint set up to return the required JavaScript previously mentioned in this guide.

1. Configure the auction. This step includes creating an auctionConfig object. This enables the seller to specify which buyer's should participate in the auction, as well as provide any signals that might be relevant during bid generation or ad scoring.
2. Execute the auction by calling navigator.runAdAuction(), passing in the configuration created in the previous step. This initiates the chain of buyers generating bids, then scoring. The end result of this step is an ad candidate that can be rendered to display an ad.
3. Render the winning ad in a fenced frame or iframe.
4. Report the result of the auction. There is a function, navigator.sendReportTo(), that will initiate reporting. The seller will always receive a report of the auction results. Only the buyer that has won the auction will receive a report. This uses the seller's reportResult() described earlier in this guide to report to their server.