Debug reporting for Protected Audience

Protected Audience debug reporting allows ad tech developers to declare remote URLs to receive a GET request from devices when an auction is won or lost. This enables the following use cases:

  • Receive reports for auction results won and lost.
  • Understand why auctions are lost. For example: Understand if it's an issue with a bidding or scoring script implementation or a core logic issue.
  • Discover issues when JavaScript logic is updated

Event-level debug reporting is available for testing in Privacy Sandbox Developer Preview 9. Debug reporting is supported on all devices where AdId is available.

The long-term plan is to enable the platform to report auction results with the Private Aggregation service. This ensures that the after-the-fact reporting cannot be used to join the custom audiences of individual users to the publisher's app. Event-level reporting is temporary, until an adequate reporting framework is released.

Learn more about debug reporting in Chrome's original FLEDGE origin trial proposal.

Usage

Debug reporting is implemented using the following JavaScript APIs, both of which take a URL string argument:

  • forDebuggingOnly.reportAdAuctionWin(String url)
  • forDebuggingOnly.reportAdAuctionLoss(String url)

The following example reports an ad auction loss with the winning bid, and an internal variable. This data can then be used for debugging purposes.

let someDebuggableVariable = 123;
const url = "https://example.com/reportLoss?winningBid=${winningBid}&someDebuggableVariable=" + someDebuggableVariable;
forDebuggingOnly.reportAdAuctionLoss(url);

The ${winningBid} template is substituted with the real value after the auction is completed.

Sellers may optionally return a rejectReason from their scoreAds function:

function scoreAd(ad, bid, auction_config, seller_signals,
                 trusted_scoring_signals, contextual_signal,
                 custom_audience_signal) {
  let score = ...
  return {
    'status': 0,
    'score': score,
    'rejectReason': 'blocked-by-publisher'
  }
}

If a seller does not set a rejection reason, then not-available is sent instead.

URL variables

The variables that can be added to the debug URL correspond to their counterparts in Chrome (though ${topLevelWinningBid} and ${topLevelMadeWinningBid} are unavailable as there is no concept of component auctions on Android).

Variable name Description
winningBid The value of the winning bid.
madeWinningBid A boolean value representing whether the buyer of this custom audience made the winning bid, either by this custom audience, or another custom audience with the same buyer.
highestScoringOtherBid The value of the bid that was scored as second highest by the seller's scoreAd script. Note that this may not be the second highest bid value, since scores and bids may be independent.
madeHighestScoringOtherBid A boolean value representing whether the buyer of this custom audience made the ${highestScoringOtherBid} bid, either by this custom audience, or another custom audience with the same buyer.
rejectReason A string optionally set by a seller explaining why they rejected a bid. Can be any of the following values:

  • not-available
  • invalid-bid
  • bid-below-auction-floor
  • pending-approval-by-exchange
  • disapproved-by-exchange
  • blocked-by-publisher
  • language-exclusions
  • category-exclusions

Constraints

  • URL host must match your enrolled Privacy Sandbox domain.
  • URL must not exceed 4096 characters including the domain, an https:// prefix, and substituted auction data.
  • In future releases, debug pings are only sent when connected to Wi-Fi.

On-device behavior

In a mobile environment, protecting memory and network usage is a core priority. As such, debug reports happen in batches.

The following system properties control the batch rate and size, which can be adjusted to lower values for development:

  • fledge_event_level_debug_reporting_batching_rate
  • fledge_event_level_debug_reporting_batch_size

The expected latency of a debug report is between 15-60 minutes after an auction has completed.

There are no hard guarantees on the completeness of debug reports. If the device reboots or the adservices process crashes before calls to the server are sent, these events are dropped.

Each ad tech has a maximum limit of 75 registered debug URLs per auction. URLs registered after that limit has been reached are silently dropped.

Finally, if the user has disabled AdId, then debug reports are sent. This is not implemented in Developer Preview 9, but will be implemented in future versions.

Ad tech server behavior

Ad tech servers should have the following behaviors for debug reporting:

  • The device sends GET requests to the server you specify with the forDebuggingOnly.* APIs.
  • Each request represents a single event-level debug report: a single ad auction win or auction loss.
  • Each request has no body. All data is in the query parameters.
  • Large response payloads can negatively impact performance and data usage, and are ignored.