Seller guide: run ad auctions

In this article, you'll find a technical reference for the ad auction, as used in the current iteration of the experimental FLEDGE API.

Read the developer guide for the full life cycle of FLEDGE, and refer to the FLEDGE explainer for an in-depth proposal of how sellers run on-device auctions.

Not a developer? Refer to the FLEDGE API overview.

# What is the FLEDGE ad auction?

A FLEDGE 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.

1. A user visits a site which displays ads. While FLEDGE is in an origin trial, the site must have an available and valid origin trial token. The user must be in an experimental group (such as Finch).

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().

   Before the auction starts, the seller finds the best contextual ad for the available ad slot.

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.

   The seller's reportResult() and buyer's reportWin() can include a call to sendReportTo(). This is available temporarily, until aggregate reporting is available with Private Aggregation.

# When does the auction take place?

FLEDGE 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 FLEDGE 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 FLEDGE 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 FLEDGE, 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': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

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

# 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:

# All FLEDGE API references

API reference guides are available:

• Developer guide for the FLEDGE API.
• Ad buyer guide to FLEDGE interest groups and bid generation.
• Ad seller guide to FLEDGE ad auctions.
• Guide to reporting auction results
• Best practices for FLEDGE ad auction latency
• Troubleshoot FLEDGE

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