diff --git a/FLEDGE.md b/FLEDGE.md index 8fef830ce..a83f1a41f 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -121,6 +121,7 @@ const myGroup = { 'executionMode': ..., 'trustedBiddingSignalsURL': ..., 'trustedBiddingSignalsKeys': ['key1', 'key2'], + 'trustedBiddingSignalsSlotSizeMode' : 'slot-size', 'userBiddingSignals': {...}, 'ads': [{renderUrl: shoesAd1, sizeGroup: 'group1', ...}, {renderUrl: shoesAd2, sizeGroup: 'group2', ...}, @@ -130,10 +131,10 @@ const myGroup = { {renderUrl: gymShoes, sizeGroup; 'group2', ...}, {renderUrl: gymTrainers1, sizeGroup: 'size4', ...}, {renderUrl: gymTrainers2, sizeGroup: 'size4', ...}], - 'adSizes': {'size1': {width: width1, height: height1}, - 'size2': {width: width2, height: height2}, - 'size3': {width: width3, height: height3}, - 'size4': {width: width4, height: height4}}, + 'adSizes': {'size1': {width: '100', height: '100'}, + 'size2': {width: '100', height: '200'}, + 'size3': {width: '75', height: '25'}, + 'size4': {width: '100', height: '25'}}, 'sizeGroups:' {'group1': ['size1', 'size2', 'size3'], 'group2': ['size3', 'size4']}, 'auctionServerRequestFlags': ['omit-ads'], @@ -313,7 +314,8 @@ const myAuctionConfig = { 'trustedScoringSignalsURL': ..., 'interestGroupBuyers': ['https://www.example-dsp.com', 'https://buyer2.com', ...], 'auctionSignals': {...}, - 'requestedSize': {width: 100, height: 200}, + 'requestedSize': {width: '100', height: '200'}, + 'allSlotsRequestedSizes': [{width: '100', height: '200'}, {width: '200', height: '300'}, ...], 'directFromSellerSignals': 'https://www.example-ssp.com/...', 'sellerSignals': {...}, 'sellerTimeout': 100, @@ -371,6 +373,8 @@ This will cause the browser to execute the appropriate bidding and auction logic The optional `requestedSize` field recommends a frame size for the auction, which will be available to bidders in browser signals. This size should be specified in the same format as the sizes in the `adSizes` field of `joinAdInterestGroup`. For convenience, the returned fenced frame config will automatically populate a ``'s `width` and `height` attributes with the `requestedSize` when loaded, though the element's size attributes can still be modified if you want to change the element's container size. Bidders inside the auction may pick a different content size for the ad, and that resulting size will be visually scaled to fit inside the element's container size. +`allSlotsRequestedSizes` may optionally be used to specify the size of all ad slots on the page, to be passed to each interest group's `trustedBuyerSignalsURL`, for interest groups that request it. All sizes in the list must be distinct. + The optional `directFromSellerSignals` field can also be used to pass signals to the auction, similar to `sellerSignals`, `perBuyerSignals`, and `auctionSignals`. The difference is that `directFromSellerSignals` are trusted to come from the seller because the content loads from a [subresource bundle](https://github.com/WICG/webpackage/blob/main/explainers/subresource-loading.md) loaded from a seller's origin, ensuring the authenticity and integrity of the signals. For more details, see [2.5 directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals). In some cases, multiple SSPs may want to participate in an auction, with the winners of separate auctions being passed up to another auction, run by another SSP. To facilitate these "component auctions", `componentAuctions` can optionally contain additional auction configurations for each seller's "component auction". The winning bid of each of these "component auctions" will be passed to the "top-level" auction. How bids are scored in this case is further described in [2.4 Scoring Bids in Component Auctions](#24-scoring-bids-in-component-auctions). The `AuctionConfig` of component auctions may not have their own `componentAuctions`. When `componentAuctions` is non-empty, `interestGroupBuyers` must be empty. That is, for any particular Protected Audience auction, either there is a single seller and no component auctions, or else all bids come from component auctions and the top-level auction can only choose among the component auctions' winners. @@ -589,11 +593,11 @@ Buyers have three basic jobs in the on-device ad auction: #### 3.1 Fetching Real-Time Data from a Trusted Server -Buyers may want to make on-device decisions that take into account real-time data (for example, the remaining budget of an ad campaign). This need can be met using the interest group's `trustedBiddingSignalsURL` and `trustedBiddingSignalsKeys` fields. Once a seller initiates an on-device auction on a publisher page, the browser checks each participating interest group for these fields, and makes an uncredentialed (cookieless) HTTP fetch to a URL of the form: +Buyers may want to make on-device decisions that take into account real-time data (for example, the remaining budget of an ad campaign). This need can be met using the interest group's `trustedBiddingSignalsURL`, `trustedBiddingSignalsKeys`, and, optionally, `trustedBiddingSignalsSlotSizeMode` fields. Once a seller initiates an on-device auction on a publisher page, the browser checks each participating interest group for these fields, and makes an uncredentialed (cookieless) HTTP fetch to a URL of the form: - https://www.kv-server.example/getvalues?hostname=publisher.com&keys=key1,key2&interestGroupNames=name1,name2&experimentGroupId=12345 + https://www.kv-server.example/getvalues?hostname=publisher.com&keys=key1,key2&interestGroupNames=name1,name2&experimentGroupId=12345&slotSize=100,200 -The base URL `https://www.kv-server.example/getvalues` comes from the interest group's `trustedBiddingSignalsURL`, the hostname of the top-level webpage where the ad will appear `publisher.com` is provided by the browser, `experimentGroupId` comes from `perBuyerExperimentGroupIds` if provided, `keys` is a list of `trustedBiddingSignalsKeys` strings, and `interestGroupNames` is a list of the names of the interest groups that data is being fetched for. The requests may be coalesced (for efficiency) across any number of interest groups that share a `trustedBiddingSignalsURL` (which means they also share an owner). +The base URL `https://www.kv-server.example/getvalues` comes from the interest group's `trustedBiddingSignalsURL`, the hostname of the top-level webpage where the ad will appear `publisher.com` is provided by the browser, `experimentGroupId` comes from `perBuyerExperimentGroupIds` if provided, `keys` is a list of `trustedBiddingSignalsKeys` strings, and `interestGroupNames` is a list of the names of the interest groups that data is being fetched for. `trustedBiddingSignalsSlotSizeMode` is one of `none` (which is the default), `slot-size`, and `all-slots-requested-sizes`. In the second case, `&slotSize=,` is appended to the URL, where width and height are the normalized width and height from the `requestedSize` of the (component) auction's AuctionConfig. "Normalized" means units are always appended, and trailing zeros are removed, so {width: "62.50sw", height: "10.0"} becomes "62.5sw,10px". In the `all-slots-requested-sizes` case, `&allSlotsRequestedSizes=,,,,...` is appended, where all sizes are taken from the (component) auction's `allSlotsRequestedSizes` value. If the corresponding value is not present in the auction configuration, no value is appended. The requests may be coalesced (for efficiency) across any number of interest groups that share a `trustedBiddingSignalsURL` and `trustedBiddingSignalsSlotSizeMode` (which means they also share an owner). The response from the server should be a JSON object of the form: