diff --git a/bidding_auction_for_debugging_only_design.md b/bidding_auction_for_debugging_only.md similarity index 54% rename from bidding_auction_for_debugging_only_design.md rename to bidding_auction_for_debugging_only.md index c21f0bc..7862e89 100644 --- a/bidding_auction_for_debugging_only_design.md +++ b/bidding_auction_for_debugging_only.md @@ -1,7 +1,8 @@ # Protected Audience forDebuggingOnly API with Bidding & Auction Services **Author:**
-[Rashmi Rao][0], Google Privacy Sandbox +[Rashmi Rao][0], Google Privacy Sandbox
+[Prakhar Mittal][1], Google Privacy Sandbox [Bidding and Auction Services](https://github.com/privacysandbox/fledge-docs/blob/main/bidding_auction_services_api.md) (B&A) outlines a way to allow Protected Audience auctions to take place in a [Trusted Execution Environment](https://github.com/privacysandbox/fledge-docs/blob/main/trusted_services_overview.md#trusted-execution-environment) (TEE) hosted on a [supported cloud platform](https://github.com/privacysandbox/fledge-docs/blob/main/bidding_auction_services_api.md#supported-public-cloud-platforms). @@ -29,7 +30,7 @@ The `forDebuggingOnly` support with Bidding and Auction Services is planned to b - Debug reporting for device-Orchestrated multi-seller auctions + Debug reporting for device-orchestrated multi-seller auctions Launched (Jan 2025) @@ -45,12 +46,12 @@ The `forDebuggingOnly` support with Bidding and Auction Services is planned to b This document details the design to generate and ping fDO URLs with the Bidding and Auction Services for single-seller and device-orchestrated multi-seller auctions. -_Note: forDebuggingOnly (fDO) API is only supported for Protected Audience auctions initiated from Chrome. +**Note:** forDebuggingOnly (fDO) API is only supported for Protected Audience auctions initiated from Chrome. # Background -During the auction, untrusted bidding logic of a DSP and untrusted decision logic of a SSP are run in sandbox environments and hence limit their ability to generate auction performance reports to their respective DSP or SSP. fDO APIs _([proposed in the first Origin Trial of Protected Audience](https://github.com/WICG/turtledove/blob/main/Proposed_First_FLEDGE_OT_Details.md#reporting))_ allow adtech to accurately measure their key business metrics and performance while running Protected Audience auctions on the Bidding and Auction Services. +During the auction, untrusted bidding logic of a DSP and untrusted decision logic of a SSP are run in sandbox environments and hence limit their ability to generate auction performance reports to their respective DSP or SSP. fDO APIs _([proposed in the first Origin Trial of Protected Audience](https://github.com/WICG/turtledove/blob/main/Proposed_First_FLEDGE_OT_Details.md#reporting))_ allow the ad tech to accurately measure their key business metrics and performance while running Protected Audience auctions on the Bidding and Auction Services. Bidding and Auction Services enable processing Protected Audience auctions on the server. Sellers use a `scoreAd()` UDF to score ads in the Auction Service and buyers use a `generateBid()` UDF for generating the bids in the Bidding Service. The flow of Bidding and Auction Services is as described in the [high-level design](https://github.com/privacysandbox/protected-auction-services-docs/blob/main/bidding_auction_services_api.md#high-level-design). This design details the support for @@ -63,40 +64,35 @@ This API allows ad techs to generate the fDO URL for losing interest groups: ``` -function forDebuggingOnly.reportAdAuctionLoss(url){ +function forDebuggingOnly.reportAdAuctionLoss(url) { // … } ``` - ## `forDebuggingOnly.reportAdAuctionWin()` JS API This API allows ad techs to generate the fDO URL for winning interest group: ``` -function forDebuggingOnly.reportAdAuctionWin(url){ +function forDebuggingOnly.reportAdAuctionWin(url) { // … } ``` - - - # Design -B&A will allow adtech to register their win and loss auction fDO URLs with a fixed set of placeholders. The placeholder data is replaced by corresponding values after the auction. +B&A will allow the ad tech to register their win and loss auction fDO URLs with a fixed set of placeholders. The placeholder data is replaced by corresponding values after the auction. Allowed placeholder keywords: - - -* `"${winningBid}"` -* `"${winningBidCurrency}"` -* `"${madeWinningBid}"` -* `"${highestScoringOtherBid}"` +* `"${winningBid}"` +* `"${winningBidCurrency}"` +* `"${madeWinningBid}"` +* `"${rejectReason}"` +* `"${highestScoringOtherBid}"` * `"${highestScoringOtherBidCurrency}"` * `"${madeHighestScoringOtherBid}"` @@ -105,29 +101,33 @@ Learn more about the keywords from [this](https://github.com/WICG/turtledove/blo ## Detailed flow - - * Adtech can register win and loss auction fDO URLs during execution of `generateBid()` and `scoreAd()` worklets. Adtech can only set at max one win and loss URL per bid. * Flow for DSP: - * Bidding Service gets the fDO urls in the response from Roma after executing `generateBid()` UDF. - * The bids along with the reporting URLs are dropped when the bid value is 0. - * For valid bids, the URLs are exported as a part of `AdWithBid` from [Roma](https://github.com/privacysandbox/protected-auction-services-docs/blob/ec0a88b2fb7f98489304d7a80a04519d68517d52/roma_bring_your_own_binary.md) and sent to the BFE, then forwarded to the SFE in `GetBidsResponse`. + * Bidding Service gets the fDO URLs in the response from Roma after executing `generateBid()` UDF. + * The bids along with the fDO URLs are dropped when the bid value is 0. + * For valid bids, the URLs are exported as a part of `AdWithBid` from Roma, then sent to the BFE in `GenerateBidsResponse`, then forwarded to the SFE in `GetBidsResponse`. + * After the winner is determined in the Auction Service, it sends the data required for replacing the placeholders in the fDO URLs to the SFE. + * In the SFE: + * The placeholders are replaced with appropriate values. + * For single-seller auctions: + * The URLs registered via `forDebuggingOnly.reportAdAuctionWin()` for the winning bid and `forDebuggingOnly.reportAdAuctionLoss()` for all the losing bids are pinged asynchronously from the SFE. + * For [device-orchestrated multi-seller auctions](https://github.com/privacysandbox/protected-auction-services-docs/blob/main/bidding_auction_services_multi_seller_auctions.md#device-orchestrated-component-auctions): + * The URLs registered via `forDebuggingOnly.reportAdAuctionWin()` and `forDebuggingOnly.reportAdAuctionLoss()` for the winning bid are sent to the client in the encrypted B&A response. The appropriate debug ping will be sent from the device depending on whether the bid wins or loses in the top-level auction. + * The URLs registered via `forDebuggingOnly.reportAdAuctionLoss()` for all the losing bids are pinged asynchronously from the SFE. * Flow for SSP: - * Auction Service gets the fDO urls in the response from Roma after executing `scoreAd()` UDF. + * Auction Service gets the fDO URLs in the response from Roma after executing `scoreAd()` UDF. * After the winner is determined in the Auction Service: - * The placeholder data is replaced in the URLs - * For single seller auctions: - * The URL registered via `forDebuggingOnly.reportAdAuctionWin()` for the winning ad / bid and `forDebuggingOnly.reportAdAuctionLoss()` for all the losing ads / bids are pinged asynchronously from the Auction Service. - * For [device orchestrated multi seller auctions](https://github.com/privacysandbox/protected-auction-services-docs/blob/main/bidding_auction_services_multi_seller_auctions.md#device-orchestrated-component-auctions): - * The URL registered via `forDebuggingOnly.reportAdAuctionWin()` and `forDebuggingOnly.`reportAdAuctionLoss`()` for the winning Ad are sent to SFE that are forwarded to the client in encrypted B&A response. URLs registered via `forDebuggingOnly.reportAdAuctionLoss()` for all the losing ads / bids are pinged asynchronously from the Auction Service. -* The data required for replacing the placeholders in the fDO URLs for the buyers is sent to SFE from Auction Service. -* In SFE, for each buyer’s fDO URL: - * The placeholders are replaced. - * The url registered via `forDebuggingOnly.reportAdAuctionWin()` for the winning bid and `forDebuggingOnly.reportAdAuctionLoss()` for all the losing bids are pinged asynchronously. + * The placeholders are replaced with appropriate values. + * For single-seller auctions: + * The URLs registered via `forDebuggingOnly.reportAdAuctionWin()` for the winning ad and `forDebuggingOnly.reportAdAuctionLoss()` for all the losing ads are pinged asynchronously from the Auction Service. + * For [device-orchestrated multi-seller auctions](https://github.com/privacysandbox/protected-auction-services-docs/blob/main/bidding_auction_services_multi_seller_auctions.md#device-orchestrated-component-auctions): + * The URLs registered via `forDebuggingOnly.reportAdAuctionWin()` and `forDebuggingOnly.reportAdAuctionLoss()` for the winning ad are sent to the SFE which forwards them to the client in the encrypted B&A response. + * The URLs registered via `forDebuggingOnly.reportAdAuctionLoss()` for all the losing ads are pinged asynchronously from the Auction Service. +* If there is any failure to ping the fDO URL, the URL is dropped. -If there is any failure to ping the fDO URL, the URL is dropped. +B&A debug reporting flow for single-seller auctions -fDo flow with B&A +B&A debug reporting flow for device-orchestrated component auctions ## Enrollment check @@ -137,22 +137,22 @@ Ad techs are required to [enroll the site](https://github.com/privacysandbox/att ## Downsampling -The device will include a field in the [ProtectedAuctionInput](https://github.com/privacysandbox/bidding-auction-servers/blob/ee8da16f9a0f282a528e3dc4b31330bbf98372f1/api/bidding_auction_servers.proto#L97) to indicate if the device is subjected to downsampling. If this flag is enabled, all URLs registered via `forDebuggingOnly` APIs will be sampled as described in the [explainer](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#712-downsampling), and the final ping will happen from the device. [ProtectedAuctionInput](https://github.com/privacysandbox/bidding-auction-servers/blob/ee8da16f9a0f282a528e3dc4b31330bbf98372f1/api/bidding_auction_servers.proto#L97) will also include a field to indicate if the device is in lockout or the AdTech is in cooldown. -This will be set in the `browserSignals.forDebuggingOnlyInCooldownOrLockout` input to `generateBid()`. - +The device will include the `enable_sampled_debug_reporting` field in the [ProtectedAuctionInput](https://github.com/privacysandbox/bidding-auction-servers/blob/ee8da16f9a0f282a528e3dc4b31330bbf98372f1/api/bidding_auction_servers.proto#L97) to indicate if the device is subjected to downsampling. If this flag is enabled, all URLs registered via `forDebuggingOnly` APIs will be sampled as described in the [explainer](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#712-downsampling), and the final fDO pings will happen from the device. -## Note for ad techs +[ProtectedAuctionInput](https://github.com/privacysandbox/bidding-auction-servers/blob/ee8da16f9a0f282a528e3dc4b31330bbf98372f1/api/bidding_auction_servers.proto#L97) will also include the `in_cooldown_or_lockout` field to indicate if the ad tech is in cooldown or the device is in lockout for downsampling. If this is true, all fDO URLs will be dropped and no fDO pings will be sent. This status will also be passed to `generateBid()` and `scoreAd()` via `browserSignals.forDebuggingOnlyInCooldownOrLockout` so that they can skip generating unnecessary fDO URLs and save execution time. +B&A debug reporting flow with downsampling +## Note for ad techs * The seller and buyer can enable fDO by setting [enableSellerDebugReportingUrlGeneration](https://github.com/privacysandbox/bidding-auction-servers/blob/722e1542c262dddc3aaf41be7b6c159a38cefd0a/production/deploy/gcp/terraform/environment/demo/seller/seller.tf#L82C1-L82C5) and [enableBuyerDebugReportingUrlGeneration](https://github.com/privacysandbox/bidding-auction-servers/blob/722e1542c262dddc3aaf41be7b6c159a38cefd0a/production/deploy/gcp/terraform/environment/demo/buyer/buyer.tf#L92) respectively to `true`. * There are two configurations that ad techs can use to limit the size of the fDO. - * Buyer can set the [MAX_ALLOWED_SIZE_DEBUG_URL_BYTES and MAX_ALLOWED_SIZE_ALL_DEBUG_URLS_KB](https://github.com/privacysandbox/bidding-auction-servers/blob/722e1542c262dddc3aaf41be7b6c159a38cefd0a/production/deploy/gcp/terraform/environment/demo/buyer/buyer.tf#L125C1-L127C1) in the Terraform configuration for bidding service. - * Seller can set the[ MAX_ALLOWED_SIZE_DEBUG_URL_BYTES and MAX_ALLOWED_SIZE_ALL_DEBUG_URLS_KB ](https://github.com/privacysandbox/bidding-auction-servers/blob/722e1542c262dddc3aaf41be7b6c159a38cefd0a/production/deploy/gcp/terraform/environment/demo/seller/seller.tf#L126C1-L127C5)in the Terraform config for Auction Service. - - Any fDO url exceeding `MAX_ALLOWED_SIZE_DEBUG_URL_BYTES` will be dropped. Once the cumulative size of the fDO urls exceeds `MAX_ALLOWED_SIZE_ALL_DEBUG_URLS_KB`, the remaining fDO urls will be dropped. + * Buyer can set the [MAX_ALLOWED_SIZE_DEBUG_URL_BYTES and MAX_ALLOWED_SIZE_ALL_DEBUG_URLS_KB](https://github.com/privacysandbox/bidding-auction-servers/blob/722e1542c262dddc3aaf41be7b6c159a38cefd0a/production/deploy/gcp/terraform/environment/demo/buyer/buyer.tf#L125C1-L127C1) in the Terraform configuration for Bidding service. + * Seller can set the[ MAX_ALLOWED_SIZE_DEBUG_URL_BYTES and MAX_ALLOWED_SIZE_ALL_DEBUG_URLS_KB ](https://github.com/privacysandbox/bidding-auction-servers/blob/722e1542c262dddc3aaf41be7b6c159a38cefd0a/production/deploy/gcp/terraform/environment/demo/seller/seller.tf#L126C1-L127C5) in the Terraform configuration for Auction Service. + Any fDO URL exceeding `MAX_ALLOWED_SIZE_DEBUG_URL_BYTES` will be dropped. Once the cumulative size of the fDO URLs to be sent from one B&A service to another exceeds `MAX_ALLOWED_SIZE_ALL_DEBUG_URLS_KB`, the remaining fDO URLs will be dropped and not sent. - It is recommended to set the [MAX_ALLOWED_SIZE_DEBUG_URL_BYTES](https://github.com/privacysandbox/bidding-auction-servers/blob/722e1542c262dddc3aaf41be7b6c159a38cefd0a/production/deploy/gcp/terraform/environment/demo/buyer/buyer.tf#L125C1-L127C1) to 64kb and [MAX_ALLOWED_SIZE_ALL_DEBUG_URLS_KB](https://github.com/privacysandbox/bidding-auction-servers/blob/722e1542c262dddc3aaf41be7b6c159a38cefd0a/production/deploy/gcp/terraform/environment/demo/buyer/buyer.tf#L125C1-L127C1) to 3Mb to not incur a network traffic and processing overhead. + It is recommended to set the [MAX_ALLOWED_SIZE_DEBUG_URL_BYTES](https://github.com/privacysandbox/bidding-auction-servers/blob/722e1542c262dddc3aaf41be7b6c159a38cefd0a/production/deploy/gcp/terraform/environment/demo/buyer/buyer.tf#L125C1-L127C1) to 64 KB and [MAX_ALLOWED_SIZE_ALL_DEBUG_URLS_KB](https://github.com/privacysandbox/bidding-auction-servers/blob/722e1542c262dddc3aaf41be7b6c159a38cefd0a/production/deploy/gcp/terraform/environment/demo/buyer/buyer.tf#L125C1-L127C1) to 3 MB to not incur a network traffic and processing overhead. [0]: https://github.com/rashmijrao + [1]: https://github.com/mittalprakhar diff --git a/images/debug-reporting-device-orchestrated-component.png b/images/debug-reporting-device-orchestrated-component.png new file mode 100644 index 0000000..51c3aee Binary files /dev/null and b/images/debug-reporting-device-orchestrated-component.png differ diff --git a/images/debug-reporting-downsampled.png b/images/debug-reporting-downsampled.png new file mode 100644 index 0000000..e4804f5 Binary files /dev/null and b/images/debug-reporting-downsampled.png differ diff --git a/images/debug-reporting-single-seller.png b/images/debug-reporting-single-seller.png new file mode 100644 index 0000000..764b39d Binary files /dev/null and b/images/debug-reporting-single-seller.png differ diff --git a/images/fDO_flow.png b/images/fDO_flow.png deleted file mode 100644 index 433e8c8..0000000 Binary files a/images/fDO_flow.png and /dev/null differ diff --git a/images/fdo_flow.png b/images/fdo_flow.png deleted file mode 100644 index c881d53..0000000 Binary files a/images/fdo_flow.png and /dev/null differ