Skip to content

Latest commit

 

History

History
305 lines (226 loc) · 15.5 KB

bidding-auction-services-payload-optimization.md

File metadata and controls

305 lines (226 loc) · 15.5 KB
Raw

FLEDGE has been renamed to Protected Audience API. To learn more about the name change, see the blog post

Author:
Priyanka Chatterjee, Google Privacy Sandbox

Bidding and Auction services payload optimization

The Bidding and Auction (B&A) services outlines a strategy for allowing Protected Auction auctions (Protected Audience, Protected App Signals23) to take place in a trusted execution environment (TEE) on a supported cloud platform. This document describes steps for optimizing the size of payload uploaded from clients for Protected Audience.

As described in Bidding and Auction (B&A) services high level architecture, the seller's code in a publisher's webpage on browser or Android app sends a unified contextual and Protected Auction HTTPS request (unified request) to the seller's ad service. This request includes a contextual payload and encrypted ProtectedAuctionInput data. (The contextual payload is not HPKE encrypted; it may be TLS protected over the wire.) The seller's frontend service orchestrates GetBids requests to buyers' BuyerFrontEnd services to generate bids. The GetBids request payloads include BuyerInput and contextual signals.

Note:

  • In case of Protected Audience, clients (web browser, app) prefetch interest groups (referred to as custom audiences for Android) periodically and stored on device.
  • The ProtectedAuctionInput request payload is compressed, padded, and then encrypted by the client. The payload is decrypted and decompressed by the Bidding and Auction services.

This document provides guidance to adtechs for optimizing size of Protected Audience request payload uploaded from web browser (on desktop, Android) for B&A services. For Android app targeting, similar payload optimization strategies and solutions can be followed.

Payload optimization is a requirement for onboarding to B&A services.

Top reasons for payload optimization

The payload size optimization is important because:

  • [Latency & network cost] Large payloads can be expensive to transmit; they impact overall auction latency and increase network costs for sellers and buyers. To mitigate these effects, the total size of compressed request payload uploaded from clients is recommended to be small (less than 60 KB).

  • [Seller configured per-buyer limit] A seller may impose a per-buyer payload size limit for ProtectedAuctionInput request payload.

  • [Utility] In order to achieve good utility from Protected Audience auctions, enough interest groups must be included in per-buyer payload size limit and made available for bid generation.

Higher payload driving factors

The following fields in interest groups required for generateBid() can cause ProtectedAuctionInput payload sizes to become large, and hence can not be included in the umbrella request payload uploaded by clients.

  • ads that include renderUrl(s) and ad metadata
    • Note: There can be multiple ads per interest group.
  • adComponents
    • Note: There can be multiple ad components per ad in interest group.
  • userBiddingSignals
    • Note: There is no payload size limit on userBiddingSignals.

Note:

Payload optimization strategies

Following are the high level strategies:

  • Only a small amount of information per interest group can be sent in the request payload for B&A. This would ensure that enough interest groups fit in a per-buyer payload limit.

  • For each interest group of a buyer, only the following information can be sent in the umbrella request payload.

  • The buyer maintains an identifier (adRenderId) for each of its ads. Each ID is a short, 8-character or less bytestring (12-byte or less when Base64 encoded) that identifies the ad. Buyer would generate short identifier for each ad render url and component ad render url such that prevWins size included in browserSignals is optimized.

  • Per buyer input that include information about interest groups are compressed on the client.

  • For B&A auctions, trustedBiddingSignals is looked up from BuyerFrontEnd service. All other information in interest group required for generating bids in B&A, must be made available in trustedBiddingSignals fetched from buyer's Key/Value service.

Payload optimization guide for sellers / SSPs

  • We recommend to sellers to set per-buyer payload size limit in the range of 2 KB to 4 KB to ensure payload for enough buyers are included in ProtectedAuctionInput.

  • Sellers running B&A services, are required to incorporate perBuyerConfig to configure per-buyer payload size limit.

Payload optimization guide for buyers / DSPs

Steps for payload optimization

This section discusses solutions for optimizing per-buyer input included in compressed ProtectedAuctionInput request payload.

Step 1

The buyer creates interest groups based on first party advertiser cookie

Buyers running B&A services must ensure that trustedBiddingSignalKeys in each interest group only include a first party (1p) advertiser cookie. This would facilitate fetching data required by generateBid() for the interest group in trustedBiddingSignals from buyer's key / value service.

Step 2

The buyer generates an identifier for each ad (adRenderId) to optimize size of ad renderURL.

  • Generate an adRenderId, that is an identifier for an ad renderURL. Similarly, also generate identifier for each adComponent renderURL.
Size of adRenderId & adComponentRenderId

The ad render IDs and adComponent render IDs must be DOMString that are 8 bytes long or less. If the identifier string is Base64 encoded, it's length must be 12 bytes long or less.

Step 3

The buyer sets priority for each interest groups

Chrome allows buyers to set a priority value (floating point number) per interest group.

  • The buyer sets a priority for each interest group when interest groups are fetched by the client.

  • The browser uses these priorities to select the higher priority interest groups and drop some lower-priority interest groups if per-buyer payload size limits are reached.

Higher priority interest groups is expected to provide better utility.

Step 4

The buyer passes adRenderId to the browser during an interest group fetch and sets auctionServerRequestFlags.

The buyer running B&A services, must pass the following additional information in an interestGroup when browser fetch interest groups from the buyer's tagging servers.

  • The buyer also populates the adRenderId field in each ads object in an interest group.

  • Sets the following two flags with specific enum, that would indicate to the browser to omit the ads, adComponents and userBiddingSignals data for this interest group from the ProtectedAuctionInput request payload. This is also noted in Protected Audience API explainer.

    • The omit-ads enumeration causes the request to omit the ads and adComponents fields for this interest group from the auction blob.
    • The omit-user-bidding-signals enumeration causes the request to omit the userBiddingSignals field for this interest group from the auction blob.
     'auctionServerRequestFlags': ['omit-ads', 'omit-user-bidding-signals']

Step 5

The browser sends small amount of information in each interest group, however includes adRenderIds in prevWins fields of browserSignal objects.

The only information included in each interest group are the following. Note that the browser will not include adRenderId(s) or adComponentRenderId(s) or userBiddingSignals or any other information in interest groups.

  • interest group name
  • trustedBiddingSignalKeys: Note that this must be a first party advertiser cookie
  • browserSignals
Specification for browser signals

The specification for the browser signals for generateBid(), is illustrated in the following example.

{ 'topWindowHostname': 'www.example-publisher.com',
  'seller': 'https://www.example-ssp.com',
  'topLevelSeller': 'https://www.another-ssp.com',
  'joinCount': 5,
  'bidCount': 24,
  'recency': 1684134092,
  'prevWins': [[time1, adRenderId1],[time2, adRenderId2],...],
  'wasmHelper': ... /* a WebAssembly.Module object based on interest group's biddingWasmHelperURL */
  'dataVersion': 1, /* Data-Version value from the trusted bidding signals server's response(s) if available */
}

The browser generates browserSignals per interest group, that includes includes joinCount, bidCount, recency and prevWins; the remaining fields in browserSignals is populated by Bidding service.

The prevWins in browserSignals refers to a tuple of time-adRenderId pairs for a previous win for this interest group that occurred in the last 30 days. Note that adRenderIds are passed in prevWins instead of full ad objects.

Step 6

The buyer's generateBid() is able to handle adRenderIds, reporting Ids and generate render url for bids.

  • Bidding service passes interest groups to generateBid(), as received from the browser. This implies that these interest groups do not include ads or adComponents or userBiddingSignals. Buyer's generateBid() must be updated to handle such interest groups. Note that since ads object is omitted, ads attributes like reporting Ids are also omitted from interest groups object.

  • generateBid() ingests adRenderIds in the prevWins field in the browserSignals object.

  • The trustedBiddingSignals fetched from the buyer's Key Value Service include adRenderID, ad metadata, reporting Ids and userBiddingSignals information.

  • generateBid() recreates the ad render URLs, adComponent render URLs and reporting Ids for the final bids after buyside auction.

    • generateBid() maintains a URL template with the base URL. The variable part of the render URL is recreated using information in the interestGroup and trustedBiddingSignal arguments.

Step 7

Fetch userBiddingSignals per interest group from buyer's key / value service

This section can be skipped for buyers that don't depend on user bidding signals.

The browser will not include userBiddingSignals information in interest groups that are sent in ProtectedAuctionInput request payload.

The userBiddingSignals information per interest group can be made available in trustedBiddingSignals, if first party advertiser cookie is used as trustedBiddingSignalKeys.

Step 8

Mitigation for winning ad candidate validation

For Protected Audience, the render URL and and reporting Ids associated with the winning ad candidate returned from B&A services in encrypted response, is validated in browser to ensure that it belongs to the interest group that the browser has information about.

Since buyer's generateBid() generate render url for the bids based on the information in trustedBiddingSignals, the URL may fail validation if the browser gets out of sync with interest groups in buyer's key / value service. . Therefore, it is important to incorporate the following mitigation.

Mitigation: Chrome browser launched more frequent interest group updates triggered by trustedBiddingSignals, refer to Intent-To-Ship for more information. With B&A, the trustedBiddingSignals are sent back to the BuyerFrontEnd service from buyer's Key / Value service. B&A would indicate to the browser in encrypted AuctionResult about how frequently or which interest groups require more frequent updates. Buyers must incorporate this feature to keep the browser in better sync with the interest group information in buyer's key / value service. This will help mitigate the render url validation failure issue.

Related material