Report on FLEDGE auction results

In this article, you'll find a technical reference for generating reports for FLEDGE auction wins, 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 event-level reporting (temporary).

Not a developer? Refer to the FLEDGE API overview.

# What does FLEDGE report?

There are two available FLEDGE reports:

• Seller report: Informs the seller of the ad auction winner.
• Buyer report: Available to winning buyers only, to learn that they've won an auction.

The long-term plan is to allow the browser to report auction results for the seller and buyers with the Private Aggregation API APIs. As a temporary event-level reporting mechanism, the code implementing reportResult() for the seller, and reportWin() for the winning bidder, can call the sendReportTo() function. This takes a single argument: a string representing a URL that is fetched after the auction completes, which encodes event-level information to be reported.

# API functions

# Seller: reportResult()

The seller's JavaScript provided in decisionLogicUrl (which also provides scoreAd()) can include a reportResult() function, to report the auction outcome.

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

The arguments passed to this function are:

# auctionConfig

The auction configuration object passed to navigator.runAdAuction().

# browserSignals

An object constructed by the browser providing information about the auction. For example:

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

The return value of this function is used as the sellerSignals argument for the winning bidder's reportWin() function.

# Buyer: reportWin()

The winning bidder's JavaScript (which also provided generateBid()) can include a reportWin() function to report the auction outcome.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

The arguments passed to this function are:

# auctionSignals and perBuyerSignals

The same values passed to generateBid() for the winning bidder.

# sellerSignals

The return value of reportResult(), which gives the seller an opportunity to pass information to the buyer.

# browserSignals

An object constructed by the browser providing information about the auction. For example:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

# Temporary reporting implementation

There are two methods available temporarily in Chrome for auction reporting:

• forDebuggingOnly.reportAdAuctionLoss()
• forDebuggingOnly.reportAdAuctionWin()

These methods each take a single argument: a URL to fetch after the auction is completed. They can be called multiple times, in both scoreAd() and generateBid(), with different URL arguments.

Chrome only sends debug loss/win reports when an auction runs to completion. If an auction is canceled (for example, due to a new navigation) no reports will be generated.

These methods are available by default in Chrome if chrome://flags/#privacy-sandbox-ads-apis is enabled. But, if you're running Chrome with command line flags to enable FLEDGE, you'll need to explicitly enable the methods by including the BiddingAndScoringDebugReportingAPI flag. If the flag is not enabled, the methods will still be available but do nothing.

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

# What's next?

We want to engage in conversations with you to ensure we build an API that works for everyone.

# Discuss the API

Like other Privacy Sandbox proposals, this API is documented and discussed publicly.

# Experiment with the API

You can experiment and participate in conversation about the FLEDGE API.