diff --git a/FLEDGE_browser_bidding_and_auction_API.md b/FLEDGE_browser_bidding_and_auction_API.md index 4b6c7b014..bdbc3e471 100644 --- a/FLEDGE_browser_bidding_and_auction_API.md +++ b/FLEDGE_browser_bidding_and_auction_API.md @@ -17,13 +17,33 @@ const auctionBlob = navigator.getInterestGroupAdAuctionData({ // ‘seller’ works the same as for runAdAuction. 'seller': 'https://www.example-ssp.com', // 'coordinatorOrigin' of the TEE coordinator, defaults to - //'https://publickeyservice.gcp.privacysandboxservices.com' (for now). Used to - // select which key to use for the encrypted blob. Will eventually be - // required. + //'https://publickeyservice.pa.gcp.privacysandboxservices.com/' (for now). Used to + // select which coordinator to use for fetching the key used to encrypt the request + // blob. Will eventually be required. 'coordinatorOrigin': - 'https://publickeyservice.gcp.privacysandboxservices.com', + 'https://publickeyservice.pa.gcp.privacysandboxservices.com/', + // 'requestSize' the affects the size of the returned request (optional). + 'requestSize': 51200, + // 'perBuyerConfig' specifies per-buyer options for size optimizations when + // constructing the blob (optional). + 'perBuyerConfig': { + 'https://buyer1.origin.example.com': { + // 'targetSize' specifies the size of the blob to devote to this buyer + // (optional). + "targetSize": 8192, + }, + 'https://buyer2.origin.example.com': {} + } }); ``` + +The `seller` field will be checked to ensure it matches the `seller` specified +in the auction configuration passed to `runAdAuction()` with the response. The +`coordinatorOrigin` selects which set of TEE keys should be used to encrypt this +request. The `coordinatorOrigin` must be a coordinator that is known to Chrome. +The `requestSize` and `perBuyerConfig` fields are described in more detail in +the [Request Size and Configuration](#request-size-and-configuration) section below. + The returned `auctionBlob` is a Promise that will resolve to an `AdAuctionData` object. This object contains `requestId` and `request` fields. The `requestId` contains a UUID that needs to be presented to `runAdAuction()` along with the response. The `request` field is a `Uint8Array` containing the information needed for the [ProtectedAudienceInput](https://github.com/privacysandbox/fledge-docs/blob/main/bidding_auction_services_api.md#protectedaudienceinput) in a `SelectAd` B&A call, @@ -130,6 +150,47 @@ const myAuctionConfig = { Note that since the `serverResponse` field in the config is a promise it is possible to run the on-device auction in parallel with the B&A auction. +## Request Size and Configuration + +### Request Size Controls +The `requestSize` field provided to `navigator.getInterestGroupAdAuctionData()` +can be used to specify the maximum size of the returned request. If the +`perBuyerConfig` field is not present and the blob fits into a +size bucket smaller than `requestSize` then that size will be used instead. + +If the `perBuyerConfig` field is specified and non-empty, the returned encrypted +blob will be exactly `requestSize` bytes long unless there was an error. If an error +occured then the returned blob will be 0 size and the function may throw an error. + +### Buyer Controls +If the `perBuyerConfig` field is specified then the blob will only include the +interest groups for the buyers specifically listed. If `requestSize` is not +specified then the sum of the `targetSize` of each buyer will be used for the +`requestSize`. Interest groups for each buyer will be added to the request -- in +decreasing order by the interest group's `priority` field -- until the next +interest group does not fit. + +Space can be allocated between different buyers in several different modes, depending +on what options are specified in the `perBuyerConfig`: + +1. Equally - Space is divided equally between buyers when `targetSize` is not specified. + +2. Proportionally - Space is assigned to buyers using `targetSize` as the + weight. So a buyer with a `targetSize` of 2 will can use twice as much space + as a buyer with a `targetSize` of 1. If all buyers have a `targetSize` + specified then proportional mode is used. + +3. Fixed/Mixed - Space is first allocated to buyers with `targetSize` specified. + They get up to `targetSize` bytes. The remaining space is divided equally + between the buyers that did not have `targetSize` specified. + +The browser will first process buyers with `targetSize` specified before +processing buyers without that field specified. Within either of these groups +buyers are processed in random order. Space that was allocated to a buyer but +was not used is divided up among remaining buyers based on the active allocation +mode. The browser may, as an optimization, calculate and use the maximum length +used by a buyer to better inform its allocation strategy. + ## Privacy Considerations The blobs sent to and received from the B&A servers can contain data that could be used to re-identify the user across different web sites. To prevent this data from being used to join the user’s cross-site identities, the data is encrypted with public keys whose corresponding private keys are only shared with B&A server instances running in TEEs and running public open-source binaries known to prevent cross-site identity joins (e.g. by preventing logging or other activities which might permit such joins).