From 1a2368f059dc591ca682700f4952c6d0ad0ae2e5 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 12 Dec 2022 10:50:37 -0500 Subject: [PATCH 01/60] Update generateBid() --- FLEDGE.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index f72b7ca16..4605963bf 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -452,8 +452,9 @@ generateBid(interestGroup, auctionSignals, perBuyerSignals, ... return {'ad': adObject, 'bid': bidValue, - 'render': renderUrl, - 'adComponents': [adComponent1, adComponent2, ...], + 'render': {url: renderUrl, size: {width: renderWidth, height: renderHeight}}, + 'adComponents': [{url: adComponent1, size: {width: componentWidth1, height: componentHeight1}}, + {url: adComponent2, size: {width: componentWidth2, height: componentHeight2}}, ...], 'allowComponentAuction': false}; } ``` @@ -490,7 +491,9 @@ The output of `generateBid()` contains the following fields: * ad: (optional) Arbitrary metadata about the ad which this interest group wants to show. The seller uses this information in its auction and decision logic. If not present, it's treated as if the value were null. * bid: A numerical bid that will enter the auction. The seller must be in a position to compare bids from different buyers, therefore bids must be in some seller-chosen unit (e.g. "USD per thousand"). If the bid is zero or negative, then this interest group will not participate in the seller's auction at all. With this mechanism, the buyer can implement any advertiser rules for where their ads may or may not appear. -* render: A URL which will be rendered to display the creative if this bid wins the auction. +* render: A dictionary describing the creative that should be rendered if this bid wins the auction. This includes: + * url: The creative's URL. + * size: A dictionary containing `width` and `height` fields, describing the creative's size. * adComponents: (optional) A list of up to 20 adComponent strings from the InterestGroup's adComponents field. Each value must match an adComponent renderUrl exactly. This field must not be present if the InterestGroup has no adComponent field. It is valid for this field not to be present even when adComponents is present. (See ["Ads Composed of Multiple Pieces"](#34-ads-composed-of-multiple-pieces) below.) * allowComponentAuction: If this buyer is taking part of a component auction, this value must be present and true, or the bid is ignored. This value is ignored (and may be absent) if the buyer is part of a top-level auction. From ff42d5bb134175b9bfff610fd97a48fd538c8eb6 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 13 Dec 2022 10:32:13 -0500 Subject: [PATCH 02/60] Most of joinAdInterestGroup changes --- FLEDGE.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 4605963bf..81125a835 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -106,8 +106,20 @@ const myGroup = { 'trustedBiddingSignalsUrl': ..., 'trustedBiddingSignalsKeys': ['key1', 'key2'], 'userBiddingSignals': {...}, - 'ads': [shoesAd1, shoesAd2, shoesAd3], - 'adComponents': [runningShoes1, runningShoes2, gymShoes, gymTrainers1, gymTrainers2], + 'ads': [{renderUrl: shoesAd1, sizeGroup: 'size1', ...}, + {renderUrl: shoesAd2, sizeGroup: 'size2', ...}, + {renderUrl: shoesAd3, sizeGroup: 'size3', ...}], + 'adComponents': [{renderUrl: runningShoes1, sizeGroup: 'group2', ...}, + {renderUrl: runningShoes2, sizeGroup: 'group2', ...}, + {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}}, + 'sizeGroups:' {'group1': ['size1', 'size2', 'size3'], + 'group2': ['size3', 'size4']}, }; const joinPromise = navigator.joinAdInterestGroup(myGroup, 30 * kSecsPerDay); ``` @@ -136,9 +148,13 @@ The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically The `executionMode` attribute is optional. The default value (`"compatibility"`) will run each invocation of `generateBid` in a totally fresh execution environment, which prevents one invocation from directly passing data to a subsequent invocation, but has non-trivial execution costs as each execution environment must be initialized from scratch. The `"groupByOrigin"` mode will attempt to re-use the execution environment for interest groups with the same script that were joined on the same top-level origin, which saves a lot of these initialization costs. However, to avoid cross-site information leaking into `generateBid`, attempts to join or leave an interest group in `"groupByOrigin"` mode from more than one top-level origin will result in all `"groupByOrigin"` interest groups that were joined from the same top-level origin being removed. When the execution environment is re-used the script top-level will not be re-executed, with only the `generateBid` function being run the subsequent times. This mode is intended for interest groups that are extremely likely to be joined or left from a single top-level origin only, with the probability high enough that the penalty of removal if the requirement doesn't hold to be low enough for the performance gains to be a worthwhile trade-off. -The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes both a rendering URL and arbitrary metadata that can be used at bidding time. +The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes a rendering URL, a size group (see below), and arbitrary metadata that can be used at bidding time. -The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes both a rendering URL and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. +The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, a size group (see below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. + +The `adSizes` field contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, TODO + +The `sizeGroups` field contains a dictionary of named lists of ad sizes. TODO All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. From d63d8e13537e697c93c52f7929da3cc06cb9ce4e Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 13 Dec 2022 12:49:09 -0500 Subject: [PATCH 03/60] Expand description of joinAdInterestGroup fields --- FLEDGE.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 81125a835..6db756dfa 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -148,13 +148,13 @@ The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically The `executionMode` attribute is optional. The default value (`"compatibility"`) will run each invocation of `generateBid` in a totally fresh execution environment, which prevents one invocation from directly passing data to a subsequent invocation, but has non-trivial execution costs as each execution environment must be initialized from scratch. The `"groupByOrigin"` mode will attempt to re-use the execution environment for interest groups with the same script that were joined on the same top-level origin, which saves a lot of these initialization costs. However, to avoid cross-site information leaking into `generateBid`, attempts to join or leave an interest group in `"groupByOrigin"` mode from more than one top-level origin will result in all `"groupByOrigin"` interest groups that were joined from the same top-level origin being removed. When the execution environment is re-used the script top-level will not be re-executed, with only the `generateBid` function being run the subsequent times. This mode is intended for interest groups that are extremely likely to be joined or left from a single top-level origin only, with the probability high enough that the penalty of removal if the requirement doesn't hold to be low enough for the performance gains to be a worthwhile trade-off. -The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes a rendering URL, a size group (see below), and arbitrary metadata that can be used at bidding time. +The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes a rendering URL, a named size group (see below), and arbitrary metadata that can be used at bidding time. -The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, a size group (see below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. +The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, a named size group (see below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. -The `adSizes` field contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, TODO +The `adSizes` field contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, where the values can have either pixel units (e.g. `100` or `'100px'`) or screen dimension coordinates (e.g. `100sw` or `100sh`). For example, the size `{width: '100sw', height: 50}` describes an ad that is the width of the screen and 50 pixels tall. The size `{width: '100sw', height: '200sw'}` describes an ad that is the width of the screen and has a 1:2 aspect ratio. -The `sizeGroups` field contains a dictionary of named lists of ad sizes. TODO +The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at (for filtering during the auction and k-anonymity checks). Each named ad size is also considered a size group, so you don't need to manually define singleton size groups. All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. From 8851afcaeeac01814128c67d07bd77cc6994659d Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 13 Dec 2022 13:05:42 -0500 Subject: [PATCH 04/60] Add runAdAuction requestedSize field --- FLEDGE.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/FLEDGE.md b/FLEDGE.md index 6db756dfa..47759ac42 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -203,6 +203,7 @@ const myAuctionConfig = { 'trustedScoringSignalsUrl': ..., 'interestGroupBuyers': ['https://www.example-dsp.com', 'https://buyer2.com', ...], 'auctionSignals': {...}, + 'requestedSize': {width: 100, height: 200}, 'directFromSellerSignals: 'https://www.example-ssp.com/...', 'sellerSignals': {...}, 'sellerTimeout': 100, @@ -242,6 +243,8 @@ const auctionResultPromise = navigator.runAdAuction(myAuctionConfig); This will cause the browser to execute the appropriate bidding and auction logic inside a collection of dedicated worklets associated with the buyer and seller domains. The `auctionSignals`, `sellerSignals`, and `perBuyerSignals` values will be passed as arguments to the appropriate functions that run inside those worklets — the `auctionSignals` are made available to everyone, while the other signals are given only to one party. +The optional `requestedSize` field recommends a frame size for the auction, which will be available to bidders in browser signals. Bidders inside the auction may pick a different size, but that resulting size will be scaled to fit inside the requested size. The returned fenced frame config will automatically populate a `` with the right size when loaded, unless the size is overridden with the element attributes. + 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`. From d662fb73dc0ff341c66058cba1794246f0c1e797 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 13 Dec 2022 13:19:01 -0500 Subject: [PATCH 05/60] Update generateBid description --- FLEDGE.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 47759ac42..8abc8e007 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -493,6 +493,7 @@ The arguments to `generateBid()` are: { 'topWindowHostname': 'www.example-publisher.com', 'seller': 'https://www.example-ssp.com', 'topLevelSeller': 'https://www.another-ssp.com', + 'requestedSize': {width: 100, height: 200}, 'joinCount': 3, 'bidCount': 17, 'prevWins': [[time1,ad1],[time2,ad2],...], @@ -512,8 +513,8 @@ The output of `generateBid()` contains the following fields: * bid: A numerical bid that will enter the auction. The seller must be in a position to compare bids from different buyers, therefore bids must be in some seller-chosen unit (e.g. "USD per thousand"). If the bid is zero or negative, then this interest group will not participate in the seller's auction at all. With this mechanism, the buyer can implement any advertiser rules for where their ads may or may not appear. * render: A dictionary describing the creative that should be rendered if this bid wins the auction. This includes: * url: The creative's URL. - * size: A dictionary containing `width` and `height` fields, describing the creative's size. -* adComponents: (optional) A list of up to 20 adComponent strings from the InterestGroup's adComponents field. Each value must match an adComponent renderUrl exactly. This field must not be present if the InterestGroup has no adComponent field. It is valid for this field not to be present even when adComponents is present. (See ["Ads Composed of Multiple Pieces"](#34-ads-composed-of-multiple-pieces) below.) + * size: A dictionary containing `width` and `height` fields, describing the creative's size (see the interest group declaration above). +* adComponents: (optional) A list of up to 20 adComponent strings from the InterestGroup's adComponents field. Each value must match an adComponent renderUrl and size exactly. This field must not be present if the InterestGroup has no adComponent field. It is valid for this field not to be present even when adComponents is present. (See ["Ads Composed of Multiple Pieces"](#34-ads-composed-of-multiple-pieces) below.) * allowComponentAuction: If this buyer is taking part of a component auction, this value must be present and true, or the bid is ignored. This value is ignored (and may be absent) if the buyer is part of a top-level auction. `generateBid()` has access to the `setPrioritySignalsOverride(key, value)` method. This adds an entry to the current interest group's `prioritySignalsOverrides` dictionary with the specified `key` and `value`, overwriting the previous value, if there was already an entry with `key`. If `value` is null, the entry with the specified key is deleted, if it exists. From 038f2ca9ab65afeb868f03d6ad69e3093441838b Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 13 Dec 2022 13:19:43 -0500 Subject: [PATCH 06/60] Update FLEDGE.md --- FLEDGE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 8abc8e007..65f893120 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -512,8 +512,8 @@ The output of `generateBid()` contains the following fields: * ad: (optional) Arbitrary metadata about the ad which this interest group wants to show. The seller uses this information in its auction and decision logic. If not present, it's treated as if the value were null. * bid: A numerical bid that will enter the auction. The seller must be in a position to compare bids from different buyers, therefore bids must be in some seller-chosen unit (e.g. "USD per thousand"). If the bid is zero or negative, then this interest group will not participate in the seller's auction at all. With this mechanism, the buyer can implement any advertiser rules for where their ads may or may not appear. * render: A dictionary describing the creative that should be rendered if this bid wins the auction. This includes: - * url: The creative's URL. - * size: A dictionary containing `width` and `height` fields, describing the creative's size (see the interest group declaration above). + * url: The creative's URL. + * size: A dictionary containing `width` and `height` fields, describing the creative's size (see the interest group declaration above). * adComponents: (optional) A list of up to 20 adComponent strings from the InterestGroup's adComponents field. Each value must match an adComponent renderUrl and size exactly. This field must not be present if the InterestGroup has no adComponent field. It is valid for this field not to be present even when adComponents is present. (See ["Ads Composed of Multiple Pieces"](#34-ads-composed-of-multiple-pieces) below.) * allowComponentAuction: If this buyer is taking part of a component auction, this value must be present and true, or the bid is ignored. This value is ignored (and may be absent) if the buyer is part of a top-level auction. From 7791d780083ae3be1cd2af0d7fa047fb13aa6da8 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 13 Dec 2022 13:21:11 -0500 Subject: [PATCH 07/60] Update FLEDGE.md --- FLEDGE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 65f893120..d86423880 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -645,6 +645,7 @@ The arguments to this function are: 'componentSeller': 'https://www.some-other-ssp.com', 'interestGroupOwner': 'https://www.example-dsp.com/', 'renderUrl': 'https://cdn.com/url-of-winning-creative.wbn', + 'renderSize': {width: 100, height: 200}, 'bid:' bidValue, 'desirability': desirabilityScoreForWinningAd, 'topLevelSellerSignals': outputOfTopLevelSellersReportResult, @@ -678,7 +679,7 @@ The arguments to this function are: * auctionSignals and perBuyerSignals: As in the call to `generateBid()` for the winning interest group. * sellerSignals: The output of `reportResult()` above, giving the seller an opportunity to pass information to the buyer. In the case where the winning buyer won a component auction and then went on to win the top-level auction, this is the output of component auction's seller's `reportResult()` method. -* browserSignals: Similar to the argument to `reportResult()` above, though without the seller's desirability score, but with an additional `seller` field. `browserSignals` may also contain the `interestGroupName` if the tuple of interest group owner, name, bidding script URL and ad creative URL were jointly k-anonymous. The `dataVersion` field will contain the `Data-Version` from the trusted bidding signals response headers if they were provided by the trusted bidding signals server response and the version was consistent for all keys requested by this interest group, otherwise the field will be absent. If the winning bid was from a component auction, then `seller` will be the seller in the component auction, a `topLevelSeller` field will contain the seller of the top level auction. Additional fields could also include some buyer-specific signal like the second-highest bid from that particular buyer. +* browserSignals: Similar to the argument to `reportResult()` above, though without the seller's desirability score, but with an additional `seller` field. `browserSignals` may also contain the `interestGroupName` if the tuple of interest group owner, name, bidding script URL and ad creative URL+size were jointly k-anonymous. The `dataVersion` field will contain the `Data-Version` from the trusted bidding signals response headers if they were provided by the trusted bidding signals server response and the version was consistent for all keys requested by this interest group, otherwise the field will be absent. If the winning bid was from a component auction, then `seller` will be the seller in the component auction, a `topLevelSeller` field will contain the seller of the top level auction. Additional fields could also include some buyer-specific signal like the second-highest bid from that particular buyer. * directFromSellerSignals is an object that may contain the following fields: * perBuyerSignals: Like auctionConfig.perBuyerSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?perBuyerSignals=[origin]`. * auctionSignals: Like auctionConfig.auctionSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?auctionSignals`. From 397e54465a5d40053110125383e965686374dfb0 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 13 Dec 2022 13:21:59 -0500 Subject: [PATCH 08/60] Update k-anon check --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index d86423880..d50bfcb9e 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -159,7 +159,7 @@ The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. -The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. +The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (url+size) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. #### 1.3 Permission Delegation From 19c08f5e79eb045cbfbc19074ff1020d802277cc Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 13 Dec 2022 13:22:41 -0500 Subject: [PATCH 09/60] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index d50bfcb9e..3a07f859e 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -657,7 +657,7 @@ The arguments to this function are: * sellerSignals: Like auctionConfig.sellerSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?sellerSignals`. * auctionSignals: Like auctionConfig.auctionSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?auctionSignals`. -The `browserSignals` argument must be handled carefully to avoid tracking. It certainly cannot include anything like the full list of interest groups, which would be too identifiable as a tracking signal. The `renderUrl` can be included since it has already passed a k-anonymity check. The browser may limit the precision of the bid and desirability values to avoid these numbers exfiltrating information from the interest group's `userBiddingSignals`. On the upside, this set of signals can be expanded to include useful additional summary data about the wider range of bids that participated in the auction, e.g. the second-highest bid or the number of bids. Additionally, the `dataVersion` will only be present if the `Data-Version` header was provided in the response headers from the Trusted Scoring server. +The `browserSignals` argument must be handled carefully to avoid tracking. It certainly cannot include anything like the full list of interest groups, which would be too identifiable as a tracking signal. The `renderUrl` and `renderSize` can be included since they hvae already passed a k-anonymity check. The browser may limit the precision of the bid and desirability values to avoid these numbers exfiltrating information from the interest group's `userBiddingSignals`. On the upside, this set of signals can be expanded to include useful additional summary data about the wider range of bids that participated in the auction, e.g. the second-highest bid or the number of bids. Additionally, the `dataVersion` will only be present if the `Data-Version` header was provided in the response headers from the Trusted Scoring server. The `reportResult()` function's reporting happens by directly calling network APIs in the short-term, but will eventually go through the Private Aggregation API once it has been developed. The output of this function is not used for reporting, but rather as an input to the buyer's reporting function. From bbc82b58416b6362b4bb5a3fb160b62576c52581 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 13 Dec 2022 13:28:29 -0500 Subject: [PATCH 10/60] Describe size macros --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 3a07f859e..d4f52e92e 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -148,7 +148,7 @@ The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically The `executionMode` attribute is optional. The default value (`"compatibility"`) will run each invocation of `generateBid` in a totally fresh execution environment, which prevents one invocation from directly passing data to a subsequent invocation, but has non-trivial execution costs as each execution environment must be initialized from scratch. The `"groupByOrigin"` mode will attempt to re-use the execution environment for interest groups with the same script that were joined on the same top-level origin, which saves a lot of these initialization costs. However, to avoid cross-site information leaking into `generateBid`, attempts to join or leave an interest group in `"groupByOrigin"` mode from more than one top-level origin will result in all `"groupByOrigin"` interest groups that were joined from the same top-level origin being removed. When the execution environment is re-used the script top-level will not be re-executed, with only the `generateBid` function being run the subsequent times. This mode is intended for interest groups that are extremely likely to be joined or left from a single top-level origin only, with the probability high enough that the penalty of removal if the requirement doesn't hold to be low enough for the performance gains to be a worthwhile trade-off. -The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes a rendering URL, a named size group (see below), and arbitrary metadata that can be used at bidding time. +The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes a rendering URL, a named size group (see below), and arbitrary metadata that can be used at bidding time. These render URLs may contain macros `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, which will be automatically replaced with the appropriate width and height after an auction, so that the initial resource request can fetch appropriately sized assets. The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, a named size group (see below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. From 0251bbc65bd53ba261b72ca06e915a52db33a46a Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 19 Dec 2022 10:35:00 -0500 Subject: [PATCH 11/60] Update Release_Notes.md --- Release_Notes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Release_Notes.md b/Release_Notes.md index cf2986b2e..22386a086 100644 --- a/Release_Notes.md +++ b/Release_Notes.md @@ -1,6 +1,10 @@ # FLEDGE Release Notes +## Chrome M111 + +* Size-related API changes would target M111 (and be backwards compatible + opt-in). We will update this with more concrete details after the implementation is done. + ## Chrome M109 From 3ef5be615a30d585990717d192d7d4c0debac2da Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Thu, 5 Jan 2023 13:09:44 -0500 Subject: [PATCH 12/60] Fix typo --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index d4f52e92e..cac166bec 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -657,7 +657,7 @@ The arguments to this function are: * sellerSignals: Like auctionConfig.sellerSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?sellerSignals`. * auctionSignals: Like auctionConfig.auctionSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?auctionSignals`. -The `browserSignals` argument must be handled carefully to avoid tracking. It certainly cannot include anything like the full list of interest groups, which would be too identifiable as a tracking signal. The `renderUrl` and `renderSize` can be included since they hvae already passed a k-anonymity check. The browser may limit the precision of the bid and desirability values to avoid these numbers exfiltrating information from the interest group's `userBiddingSignals`. On the upside, this set of signals can be expanded to include useful additional summary data about the wider range of bids that participated in the auction, e.g. the second-highest bid or the number of bids. Additionally, the `dataVersion` will only be present if the `Data-Version` header was provided in the response headers from the Trusted Scoring server. +The `browserSignals` argument must be handled carefully to avoid tracking. It certainly cannot include anything like the full list of interest groups, which would be too identifiable as a tracking signal. The `renderUrl` and `renderSize` can be included since they have already passed a k-anonymity check. The browser may limit the precision of the bid and desirability values to avoid these numbers exfiltrating information from the interest group's `userBiddingSignals`. On the upside, this set of signals can be expanded to include useful additional summary data about the wider range of bids that participated in the auction, e.g. the second-highest bid or the number of bids. Additionally, the `dataVersion` will only be present if the `Data-Version` header was provided in the response headers from the Trusted Scoring server. The `reportResult()` function's reporting happens by directly calling network APIs in the short-term, but will eventually go through the Private Aggregation API once it has been developed. The output of this function is not used for reporting, but rather as an input to the buyer's reporting function. From fc9653ff9f9c735812b1a4b548216e14f64b87a5 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Thu, 5 Jan 2023 13:26:38 -0500 Subject: [PATCH 13/60] Describe how size returned from generateBid is used --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index cac166bec..aeae8ed99 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -513,7 +513,7 @@ The output of `generateBid()` contains the following fields: * bid: A numerical bid that will enter the auction. The seller must be in a position to compare bids from different buyers, therefore bids must be in some seller-chosen unit (e.g. "USD per thousand"). If the bid is zero or negative, then this interest group will not participate in the seller's auction at all. With this mechanism, the buyer can implement any advertiser rules for where their ads may or may not appear. * render: A dictionary describing the creative that should be rendered if this bid wins the auction. This includes: * url: The creative's URL. - * size: A dictionary containing `width` and `height` fields, describing the creative's size (see the interest group declaration above). + * size: A dictionary containing `width` and `height` fields, describing the creative's size (see the interest group declaration above). When the ad is loaded in a fenced frame, the fenced frame's inner frame (i.e. the size visible to the ad creative) will be frozen to this size, and it will be unable to see changes to the frame size made by the embedder. * adComponents: (optional) A list of up to 20 adComponent strings from the InterestGroup's adComponents field. Each value must match an adComponent renderUrl and size exactly. This field must not be present if the InterestGroup has no adComponent field. It is valid for this field not to be present even when adComponents is present. (See ["Ads Composed of Multiple Pieces"](#34-ads-composed-of-multiple-pieces) below.) * allowComponentAuction: If this buyer is taking part of a component auction, this value must be present and true, or the bid is ignored. This value is ignored (and may be absent) if the buyer is part of a top-level auction. From 01ef829bb59caede235a0ee2ec1c51e01830b258 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Thu, 5 Jan 2023 13:53:01 -0500 Subject: [PATCH 14/60] Remove mention of filtering --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index aeae8ed99..25f1369f5 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -154,7 +154,7 @@ The `adComponents` field contains the various ad components (or "products") that The `adSizes` field contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, where the values can have either pixel units (e.g. `100` or `'100px'`) or screen dimension coordinates (e.g. `100sw` or `100sh`). For example, the size `{width: '100sw', height: 50}` describes an ad that is the width of the screen and 50 pixels tall. The size `{width: '100sw', height: '200sw'}` describes an ad that is the width of the screen and has a 1:2 aspect ratio. -The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at (for filtering during the auction and k-anonymity checks). Each named ad size is also considered a size group, so you don't need to manually define singleton size groups. +The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at (for prefetching k-anonymity checks). Each named ad size is also considered a size group, so you don't need to manually define singleton size groups. All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. From a0a310db9311f7f1a35eed355a5fead4fb40be30 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Thu, 5 Jan 2023 14:18:08 -0500 Subject: [PATCH 15/60] Describe purpose of sizes in interest group declaration --- FLEDGE.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 25f1369f5..4bbbf111d 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -152,9 +152,11 @@ The `ads` list contains the various ads that the interest group might show. Eac The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, a named size group (see below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. -The `adSizes` field contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, where the values can have either pixel units (e.g. `100` or `'100px'`) or screen dimension coordinates (e.g. `100sw` or `100sh`). For example, the size `{width: '100sw', height: 50}` describes an ad that is the width of the screen and 50 pixels tall. The size `{width: '100sw', height: '200sw'}` describes an ad that is the width of the screen and has a 1:2 aspect ratio. +The `adSizes` field contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, where the values can have either pixel units (e.g. `100` or `'100px'`) or screen dimension coordinates (e.g. `100sw` or `100sh`). For example, the size `{width: '100sw', height: 50}` describes an ad that is the width of the screen and 50 pixels tall. The size `{width: '100sw', height: '200sw'}` describes an ad that is the width of the screen and has a 1:2 aspect ratio. Sizes with screen dimension coordinates are primarily intended for screen-width ads on mobile devices, and may be restricted in certain contexts (to be determined) for privacy reasons. -The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at (for prefetching k-anonymity checks). Each named ad size is also considered a size group, so you don't need to manually define singleton size groups. +The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups. + +These declared ad-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. From 1ddddee38133ad195b291e801086e4b89481bcd4 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Wed, 8 Feb 2023 13:40:48 -0500 Subject: [PATCH 16/60] Update Release_Notes.md --- Release_Notes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Release_Notes.md b/Release_Notes.md index 22386a086..58f57fee9 100644 --- a/Release_Notes.md +++ b/Release_Notes.md @@ -1,9 +1,9 @@ # FLEDGE Release Notes -## Chrome M111 +## Chrome M112 -* Size-related API changes would target M111 (and be backwards compatible + opt-in). We will update this with more concrete details after the implementation is done. +* Size-related API changes are targeting M112 (and will be backwards compatible + opt-in). We will update this with more concrete details after the implementation is done. ## Chrome M109 From d642777c65d66274dc57727b59f36f13d89b3683 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Thu, 30 Mar 2023 10:29:14 -0400 Subject: [PATCH 17/60] Update Release_Notes.md --- Release_Notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Release_Notes.md b/Release_Notes.md index 58f57fee9..f8a84a021 100644 --- a/Release_Notes.md +++ b/Release_Notes.md @@ -3,7 +3,7 @@ ## Chrome M112 -* Size-related API changes are targeting M112 (and will be backwards compatible + opt-in). We will update this with more concrete details after the implementation is done. +* Size-related API changes are targeting M113 (and will be backwards compatible + opt-in). We will update this with more concrete details after the implementation is done. ## Chrome M109 From f25854c2deac1cda1cc770552e54a54e25f24764 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Thu, 30 Mar 2023 10:45:24 -0400 Subject: [PATCH 18/60] Update Release_Notes.md --- Release_Notes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Release_Notes.md b/Release_Notes.md index f8a84a021..741f6443c 100644 --- a/Release_Notes.md +++ b/Release_Notes.md @@ -1,9 +1,9 @@ # FLEDGE Release Notes -## Chrome M112 +## Chrome M113 -* Size-related API changes are targeting M113 (and will be backwards compatible + opt-in). We will update this with more concrete details after the implementation is done. +* Some of the size-related API changes (the ability to declare ad sizes in joinAdInterestGroup, include sizes with bids in generateBid, and have those sizes macro'd into the url with AD_WIDTH and AD_HEIGHT macros) will be added in M113 (and will be backwards compatible + opt-in). The ability to specify a requestedSize in the auction config (and downstream effects in browser signals and fenced frame configs) is targeting M114, because it is only a convenience feature. ## Chrome M109 From 53803681b8d63a31e5fb2cf9f5ffd1e858d9f31f Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 10 Apr 2023 13:19:44 -0400 Subject: [PATCH 19/60] Accept `sizeGroups` suggestion Co-authored-by: Paul Jensen --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index a0ed2d530..830f96227 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -167,7 +167,7 @@ The `executionMode` attribute is optional, and may contain one of the following The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes a rendering URL, a named size group (see below), and arbitrary metadata that can be used at bidding time. These render URLs may contain macros `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, which will be automatically replaced with the appropriate width and height after an auction, so that the initial resource request can fetch appropriately sized assets. -The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, a named size group (see below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. +The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, a named size group (see `sizeGroups` below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. The `adSizes` field contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, where the values can have either pixel units (e.g. `100` or `'100px'`) or screen dimension coordinates (e.g. `100sw` or `100sh`). For example, the size `{width: '100sw', height: 50}` describes an ad that is the width of the screen and 50 pixels tall. The size `{width: '100sw', height: '200sw'}` describes an ad that is the width of the screen and has a 1:2 aspect ratio. Sizes with screen dimension coordinates are primarily intended for screen-width ads on mobile devices, and may be restricted in certain contexts (to be determined) for privacy reasons. From d102fbc57cc29dc6a55c397b65ea045bfa7eaaa7 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 11 Apr 2023 15:51:08 -0400 Subject: [PATCH 20/60] Accept suggestion Co-authored-by: Paul Jensen --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 830f96227..d31fbfbda 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -165,7 +165,7 @@ The `executionMode` attribute is optional, and may contain one of the following mode does not have the same limitations on what top-level sites can join or leave the interest group. -The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes a rendering URL, a named size group (see below), and arbitrary metadata that can be used at bidding time. These render URLs may contain macros `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, which will be automatically replaced with the appropriate width and height after an auction, so that the initial resource request can fetch appropriately sized assets. +The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes a rendering URL, a named size group (see `sizeGroups` below), and arbitrary metadata that can be used at bidding time. These render URLs may contain macros `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, which will be automatically replaced with the appropriate width and height after an auction, so that the initial resource request can fetch appropriately sized assets. The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, a named size group (see `sizeGroups` below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. From 47d50e6c503f9c8f94799205fa0147a8df828b8d Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 11 Apr 2023 15:52:12 -0400 Subject: [PATCH 21/60] Accept suggestion to use group1 and group2 in ad size example Co-authored-by: Paul Jensen --- FLEDGE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index d31fbfbda..4ba74a707 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -108,8 +108,8 @@ const myGroup = { 'trustedBiddingSignalsUrl': ..., 'trustedBiddingSignalsKeys': ['key1', 'key2'], 'userBiddingSignals': {...}, - 'ads': [{renderUrl: shoesAd1, sizeGroup: 'size1', ...}, - {renderUrl: shoesAd2, sizeGroup: 'size2', ...}, + 'ads': [{renderUrl: shoesAd1, sizeGroup: 'group1', ...}, + {renderUrl: shoesAd2, sizeGroup: 'group2', ...}, {renderUrl: shoesAd3, sizeGroup: 'size3', ...}], 'adComponents': [{renderUrl: runningShoes1, sizeGroup: 'group2', ...}, {renderUrl: runningShoes2, sizeGroup: 'group2', ...}, From 568873a9cde32b3d993ab8e0a9c31a49931d189c Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 11 Apr 2023 15:52:55 -0400 Subject: [PATCH 22/60] Accept suggestion to explicitly call out the "size3" example size->sizeGroup implicit coercion Co-authored-by: Paul Jensen --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 4ba74a707..60f45922a 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -171,7 +171,7 @@ The `adComponents` field contains the various ad components (or "products") that The `adSizes` field contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, where the values can have either pixel units (e.g. `100` or `'100px'`) or screen dimension coordinates (e.g. `100sw` or `100sh`). For example, the size `{width: '100sw', height: 50}` describes an ad that is the width of the screen and 50 pixels tall. The size `{width: '100sw', height: '200sw'}` describes an ad that is the width of the screen and has a 1:2 aspect ratio. Sizes with screen dimension coordinates are primarily intended for screen-width ads on mobile devices, and may be restricted in certain contexts (to be determined) for privacy reasons. -The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups. +The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. These declared ad-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. From 0a3db48e8c8349f3c76f760c99250c44a2bcc750 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 11 Apr 2023 15:55:42 -0400 Subject: [PATCH 23/60] Accept suggestion to call out AD_WIDTH and AD_HEIGHT explicitly in "see above" Co-authored-by: Paul Jensen --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 60f45922a..8575a655c 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -173,7 +173,7 @@ The `adSizes` field contains a dictionary of named ad sizes. Each size has the f The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -These declared ad-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. +These declared ad-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. From adf4cbc57be71162ff69d846257eeada0e41c9e5 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 11 Apr 2023 15:56:40 -0400 Subject: [PATCH 24/60] Accept suggestion to turn "url+size" into "URL and size" Co-authored-by: Paul Jensen --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 8575a655c..7f60645de 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -178,7 +178,7 @@ These declared ad-size pairings will be used to prefetch k-anonymity checks, whi All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. -The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (url+size) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. +The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL and size) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. #### 1.3 Permission Delegation From cb668e8e079d2f0a2d9cdd32d9966e90048cbd1a Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 11 Apr 2023 16:03:19 -0400 Subject: [PATCH 25/60] Accept suggestion to rephrase interest group size declaration description Co-authored-by: Paul Jensen --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 7f60645de..e8f48e6e3 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -561,7 +561,7 @@ The output of `generateBid()` contains the following fields: * render: A dictionary describing the creative that should be rendered if this bid wins the auction. This includes: * url: The creative's URL. * size: A dictionary containing `width` and `height` fields, describing the creative's size (see the interest group declaration above). When the ad is loaded in a fenced frame, the fenced frame's inner frame (i.e. the size visible to the ad creative) will be frozen to this size, and it will be unable to see changes to the frame size made by the embedder. -* adComponents: (optional) A list of up to 20 adComponent strings from the InterestGroup's adComponents field. Each value must match an adComponent renderUrl and size exactly. This field must not be present if the InterestGroup has no adComponent field. It is valid for this field not to be present even when adComponents is present. (See ["Ads Composed of Multiple Pieces"](#34-ads-composed-of-multiple-pieces) below.) +* adComponents: (optional) A list of up to 20 adComponent strings from the InterestGroup's adComponents field. Each value must match one of `interestGroup`'s `adComponent`'s `renderUrl` and sizes exactly. This field must not be present if `interestGroup` has no `adComponent` field. It is valid for this field not to be present even when `adComponents` is present. (See ["Ads Composed of Multiple Pieces"](#34-ads-composed-of-multiple-pieces) below.) * allowComponentAuction: If this buyer is taking part of a component auction, this value must be present and true, or the bid is ignored. This value is ignored (and may be absent) if the buyer is part of a top-level auction. * modelingSignals: A 0-4095 integer (12-bits) passed to `reportWin()`, with noising, as described in the [noising and bucketing scheme](#521-noised-and-bucketed-signals). Invalid values, such as negative, infinite, and NaN values, will be ignored and not passed. Only the lowest 12 bits will be passed. From 733a82111108781edcbada6a9992d588434fad4f Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 24 Apr 2023 14:42:30 -0400 Subject: [PATCH 26/60] Mention optionality of interest group size fields --- FLEDGE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index e8f48e6e3..0658b1f3f 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -165,15 +165,15 @@ The `executionMode` attribute is optional, and may contain one of the following mode does not have the same limitations on what top-level sites can join or leave the interest group. -The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes a rendering URL, a named size group (see `sizeGroups` below), and arbitrary metadata that can be used at bidding time. These render URLs may contain macros `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, which will be automatically replaced with the appropriate width and height after an auction, so that the initial resource request can fetch appropriately sized assets. +The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes a rendering URL, (optionally) a named size group (see `sizeGroups` below), and arbitrary metadata that can be used at bidding time. If the size group is specified, these render URLs may contain macros `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, which will be automatically replaced with the appropriate width and height after an auction, so that the initial resource request can fetch appropriately sized assets. -The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, a named size group (see `sizeGroups` below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. +The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, (optionally) a named size group (see `sizeGroups` below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. The `adSizes` field contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, where the values can have either pixel units (e.g. `100` or `'100px'`) or screen dimension coordinates (e.g. `100sw` or `100sh`). For example, the size `{width: '100sw', height: 50}` describes an ad that is the width of the screen and 50 pixels tall. The size `{width: '100sw', height: '200sw'}` describes an ad that is the width of the screen and has a 1:2 aspect ratio. Sizes with screen dimension coordinates are primarily intended for screen-width ads on mobile devices, and may be restricted in certain contexts (to be determined) for privacy reasons. The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -These declared ad-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. +These declared url-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. From 3ec71ac526efff3988a08982e25bc5023139fc81 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 24 Apr 2023 14:45:40 -0400 Subject: [PATCH 27/60] Remark that sizes are also optional in generateBid --- FLEDGE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/FLEDGE.md b/FLEDGE.md index 0658b1f3f..c9c29da56 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -561,6 +561,8 @@ The output of `generateBid()` contains the following fields: * render: A dictionary describing the creative that should be rendered if this bid wins the auction. This includes: * url: The creative's URL. * size: A dictionary containing `width` and `height` fields, describing the creative's size (see the interest group declaration above). When the ad is loaded in a fenced frame, the fenced frame's inner frame (i.e. the size visible to the ad creative) will be frozen to this size, and it will be unable to see changes to the frame size made by the embedder. + + Optionally, if you don't want to hook into interest group size declarations (e.g., if you don't want to use size macros), you can have `render` be just the url, rather than a dictionary with `url` and `size`. * adComponents: (optional) A list of up to 20 adComponent strings from the InterestGroup's adComponents field. Each value must match one of `interestGroup`'s `adComponent`'s `renderUrl` and sizes exactly. This field must not be present if `interestGroup` has no `adComponent` field. It is valid for this field not to be present even when `adComponents` is present. (See ["Ads Composed of Multiple Pieces"](#34-ads-composed-of-multiple-pieces) below.) * allowComponentAuction: If this buyer is taking part of a component auction, this value must be present and true, or the bid is ignored. This value is ignored (and may be absent) if the buyer is part of a top-level auction. * modelingSignals: A 0-4095 integer (12-bits) passed to `reportWin()`, with noising, as described in the [noising and bucketing scheme](#521-noised-and-bucketed-signals). Invalid values, such as negative, infinite, and NaN values, will be ignored and not passed. Only the lowest 12 bits will be passed. From cfbcb70f060dc10d0544ffbcb7a439d7b533ef84 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 24 Apr 2023 14:47:24 -0400 Subject: [PATCH 28/60] Add more (optionally)s --- FLEDGE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index c9c29da56..075f51b1e 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -169,11 +169,11 @@ The `ads` list contains the various ads that the interest group might show. Eac The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, (optionally) a named size group (see `sizeGroups` below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group. -The `adSizes` field contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, where the values can have either pixel units (e.g. `100` or `'100px'`) or screen dimension coordinates (e.g. `100sw` or `100sh`). For example, the size `{width: '100sw', height: 50}` describes an ad that is the width of the screen and 50 pixels tall. The size `{width: '100sw', height: '200sw'}` describes an ad that is the width of the screen and has a 1:2 aspect ratio. Sizes with screen dimension coordinates are primarily intended for screen-width ads on mobile devices, and may be restricted in certain contexts (to be determined) for privacy reasons. +The `adSizes` field (optionally) contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, where the values can have either pixel units (e.g. `100` or `'100px'`) or screen dimension coordinates (e.g. `100sw` or `100sh`). For example, the size `{width: '100sw', height: 50}` describes an ad that is the width of the screen and 50 pixels tall. The size `{width: '100sw', height: '200sw'}` describes an ad that is the width of the screen and has a 1:2 aspect ratio. Sizes with screen dimension coordinates are primarily intended for screen-width ads on mobile devices, and may be restricted in certain contexts (to be determined) for privacy reasons. -The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. +The `sizeGroups` field (optionally) contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -These declared url-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. +These declared url-size pairings will (optionally) be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. From 7c6aa0e19a052969198abdb3c73b24fcc40ef709 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 24 Apr 2023 14:51:05 -0400 Subject: [PATCH 29/60] Update Release_Notes.md --- Release_Notes.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Release_Notes.md b/Release_Notes.md index 741f6443c..43c47f745 100644 --- a/Release_Notes.md +++ b/Release_Notes.md @@ -1,9 +1,15 @@ # FLEDGE Release Notes +## Chrome M114 + +* Support the ability to specify `requestedSize` in the auction config, which is eventually stored in the winning fenced frame config's container size. The `requestedSize` may not be accessible through browser signals in the auction until M115. + + ## Chrome M113 -* Some of the size-related API changes (the ability to declare ad sizes in joinAdInterestGroup, include sizes with bids in generateBid, and have those sizes macro'd into the url with AD_WIDTH and AD_HEIGHT macros) will be added in M113 (and will be backwards compatible + opt-in). The ability to specify a requestedSize in the auction config (and downstream effects in browser signals and fenced frame configs) is targeting M114, because it is only a convenience feature. +* Support some of the size-related API changes (the ability to declare ad sizes in `joinAdInterestGroup`, include sizes with bids in `generateBid`, and have those sizes macro'd into the url with `AD_WIDTH` and `AD_HEIGHT` macros), in a backwards compatible and opt-in way. + ## Chrome M109 From 85c2f60984429178532e78993b649986c0e8537f Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Thu, 27 Apr 2023 09:59:53 -0400 Subject: [PATCH 30/60] Add more optionality --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 075f51b1e..de8d06518 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -178,7 +178,7 @@ These declared url-size pairings will (optionally) be used to prefetch k-anonymi All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. -The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL and size) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. +The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and size if declared by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. #### 1.3 Permission Delegation From 1e0785516d994e6a064111bbcc1193f554c08037 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Thu, 27 Apr 2023 10:01:17 -0400 Subject: [PATCH 31/60] Add more optionality --- FLEDGE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index de8d06518..6bc93c12a 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -178,7 +178,7 @@ These declared url-size pairings will (optionally) be used to prefetch k-anonymi All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. -The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and size if declared by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. +The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. #### 1.3 Permission Delegation @@ -738,7 +738,7 @@ The arguments to this function are: * sellerSignals: The output of `reportResult()` above, giving the seller an opportunity to pass information to the buyer. In the case where the winning buyer won a component auction and then went on to win the top-level auction, this is the output of component auction's seller's `reportResult()` method. * browserSignals: Similar to the argument to `reportResult()` above, though without the seller's desirability score, but with additional `adCost`, `seller`, `madeHighestScoringOtherBid` and potentially `interestGroupName` fields: * The `adCost` field contains the value that was returned by `generateBid()`, stochastically rounded to fit into a floating point number with an 8 bit mantissa and 8 bit exponent. This field is only present if `adCost` was returned by `generateBid()`. - * The `interestGroupName` may be included if the tuple of interest group owner, name, bidding script URL and ad creative URL and size were jointly k-anonymous. + * The `interestGroupName` may be included if the tuple of interest group owner, name, bidding script URL, ad creative URL, and ad creative size (if specified by `generateBid`) were jointly k-anonymous. * The `madeHighestScoringOtherBid` field is true if the interest group owner was the only bidder that made bids with the second highest score. * The `highestScoringOtherBid` and `madeHighestScoringOtherBid` fields are based on the auction the interest group was directly part of. If that was a component auction, they're from the component auction. If that was the top-level auction, then they're from the top-level auction. Component bidders do not get these signals from top-level auctions since it is the auction seller joining the top-level auction, instead of winning component bidders joining the top-level auction directly. * The `dataVersion` field will contain the `Data-Version` from the trusted bidding signals response headers if they were provided by the trusted bidding signals server response and the version was consistent for all keys requested by this interest group, otherwise the field will be absent. From c1e00cf38ae130f692f5c51cc1cb86bb0792d51f Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 5 May 2023 10:34:25 -0400 Subject: [PATCH 32/60] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 6bc93c12a..af32f93cd 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -173,7 +173,7 @@ The `adSizes` field (optionally) contains a dictionary of named ad sizes. Each s The `sizeGroups` field (optionally) contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -These declared url-size pairings will (optionally) be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. +In the future, when the sizes are declared, the url-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Currently, only the url is used for k-anonymity checks.) Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. From 2d44dd9e72ee803c636b1985b273aee76bf6e7b6 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 5 May 2023 10:39:35 -0400 Subject: [PATCH 33/60] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index af32f93cd..acdb1bdea 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -178,7 +178,7 @@ In the future, when the sizes are declared, the url-size pairings will be used t All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. -The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. +The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). (For the time being, the size is excluded from the k-anonymity check even when specified by `generateBid`.) For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. #### 1.3 Permission Delegation From 76252405f929d56bec0bc8555be69d3d53627ef7 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 5 May 2023 10:41:44 -0400 Subject: [PATCH 34/60] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index acdb1bdea..4afa42d07 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -738,7 +738,7 @@ The arguments to this function are: * sellerSignals: The output of `reportResult()` above, giving the seller an opportunity to pass information to the buyer. In the case where the winning buyer won a component auction and then went on to win the top-level auction, this is the output of component auction's seller's `reportResult()` method. * browserSignals: Similar to the argument to `reportResult()` above, though without the seller's desirability score, but with additional `adCost`, `seller`, `madeHighestScoringOtherBid` and potentially `interestGroupName` fields: * The `adCost` field contains the value that was returned by `generateBid()`, stochastically rounded to fit into a floating point number with an 8 bit mantissa and 8 bit exponent. This field is only present if `adCost` was returned by `generateBid()`. - * The `interestGroupName` may be included if the tuple of interest group owner, name, bidding script URL, ad creative URL, and ad creative size (if specified by `generateBid`) were jointly k-anonymous. + * The `interestGroupName` may be included if the tuple of interest group owner, name, bidding script URL, ad creative URL, and ad creative size (if specified by `generateBid`) were jointly k-anonymous. (Note: for the time being, the ad creative size is excluded from this check in the implementation.) * The `madeHighestScoringOtherBid` field is true if the interest group owner was the only bidder that made bids with the second highest score. * The `highestScoringOtherBid` and `madeHighestScoringOtherBid` fields are based on the auction the interest group was directly part of. If that was a component auction, they're from the component auction. If that was the top-level auction, then they're from the top-level auction. Component bidders do not get these signals from top-level auctions since it is the auction seller joining the top-level auction, instead of winning component bidders joining the top-level auction directly. * The `dataVersion` field will contain the `Data-Version` from the trusted bidding signals response headers if they were provided by the trusted bidding signals server response and the version was consistent for all keys requested by this interest group, otherwise the field will be absent. From 9ecc5f6a27c7e5c11fe4e4b08e55b405e8aa813c Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 5 May 2023 10:42:19 -0400 Subject: [PATCH 35/60] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 4afa42d07..2e39610da 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -173,7 +173,7 @@ The `adSizes` field (optionally) contains a dictionary of named ad sizes. Each s The `sizeGroups` field (optionally) contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -In the future, when the sizes are declared, the url-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Currently, only the url is used for k-anonymity checks.) Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. +In the future, when the sizes are declared, the url-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Note: for the time being, only the url is used for k-anonymity checks, not the size.) Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. From 4efd2e8d544cd12f876ee239e15429451966a5d7 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 5 May 2023 10:42:45 -0400 Subject: [PATCH 36/60] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 2e39610da..184b61b1e 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -178,7 +178,7 @@ In the future, when the sizes are declared, the url-size pairings will be used t All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. -The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). (For the time being, the size is excluded from the k-anonymity check even when specified by `generateBid`.) For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. +The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). (Note: for the time being, the size is excluded from the k-anonymity check even when specified by `generateBid`.) For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. #### 1.3 Permission Delegation From 064841f664bf17a2187d063e6b6521e1d8668c87 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 5 May 2023 10:43:49 -0400 Subject: [PATCH 37/60] Update FLEDGE.md --- FLEDGE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 184b61b1e..db7322ba7 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -173,12 +173,12 @@ The `adSizes` field (optionally) contains a dictionary of named ad sizes. Each s The `sizeGroups` field (optionally) contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -In the future, when the sizes are declared, the url-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Note: for the time being, only the url is used for k-anonymity checks, not the size.) Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. +In the future, when the sizes are declared, the url-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Note: for a transition period, in the implementation, only the url is used for k-anonymity checks, not the size.) Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. -The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). (Note: for the time being, the size is excluded from the k-anonymity check even when specified by `generateBid`.) For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. +The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). (Note: for a transition period, in the implementation, the size is excluded from the k-anonymity check even when specified by `generateBid`.) For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough. #### 1.3 Permission Delegation @@ -738,7 +738,7 @@ The arguments to this function are: * sellerSignals: The output of `reportResult()` above, giving the seller an opportunity to pass information to the buyer. In the case where the winning buyer won a component auction and then went on to win the top-level auction, this is the output of component auction's seller's `reportResult()` method. * browserSignals: Similar to the argument to `reportResult()` above, though without the seller's desirability score, but with additional `adCost`, `seller`, `madeHighestScoringOtherBid` and potentially `interestGroupName` fields: * The `adCost` field contains the value that was returned by `generateBid()`, stochastically rounded to fit into a floating point number with an 8 bit mantissa and 8 bit exponent. This field is only present if `adCost` was returned by `generateBid()`. - * The `interestGroupName` may be included if the tuple of interest group owner, name, bidding script URL, ad creative URL, and ad creative size (if specified by `generateBid`) were jointly k-anonymous. (Note: for the time being, the ad creative size is excluded from this check in the implementation.) + * The `interestGroupName` may be included if the tuple of interest group owner, name, bidding script URL, ad creative URL, and ad creative size (if specified by `generateBid`) were jointly k-anonymous. (Note: for a transition period, in the implementation, the ad creative size is excluded from this check.) * The `madeHighestScoringOtherBid` field is true if the interest group owner was the only bidder that made bids with the second highest score. * The `highestScoringOtherBid` and `madeHighestScoringOtherBid` fields are based on the auction the interest group was directly part of. If that was a component auction, they're from the component auction. If that was the top-level auction, then they're from the top-level auction. Component bidders do not get these signals from top-level auctions since it is the auction seller joining the top-level auction, instead of winning component bidders joining the top-level auction directly. * The `dataVersion` field will contain the `Data-Version` from the trusted bidding signals response headers if they were provided by the trusted bidding signals server response and the version was consistent for all keys requested by this interest group, otherwise the field will be absent. From 81995084ea28d03a50ce26b0f50034de217ce69e Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 8 May 2023 12:36:36 -0400 Subject: [PATCH 38/60] Update FLEDGE.md Co-authored-by: Paul Jensen --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index db7322ba7..6538ecffb 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -173,7 +173,7 @@ The `adSizes` field (optionally) contains a dictionary of named ad sizes. Each s The `sizeGroups` field (optionally) contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -In the future, when the sizes are declared, the url-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Note: for a transition period, in the implementation, only the url is used for k-anonymity checks, not the size.) Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. +In the future, when the sizes are declared, the URL-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Note: for a transition period, in the implementation, only the URL is used for k-anonymity checks, not the size.) Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. From 81a8bf92b7e38c1410a890d72463448145899140 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 8 May 2023 12:36:46 -0400 Subject: [PATCH 39/60] Update FLEDGE.md Co-authored-by: Paul Jensen --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 6538ecffb..59bafa595 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -562,7 +562,7 @@ The output of `generateBid()` contains the following fields: * url: The creative's URL. * size: A dictionary containing `width` and `height` fields, describing the creative's size (see the interest group declaration above). When the ad is loaded in a fenced frame, the fenced frame's inner frame (i.e. the size visible to the ad creative) will be frozen to this size, and it will be unable to see changes to the frame size made by the embedder. - Optionally, if you don't want to hook into interest group size declarations (e.g., if you don't want to use size macros), you can have `render` be just the url, rather than a dictionary with `url` and `size`. + Optionally, if you don't want to hook into interest group size declarations (e.g., if you don't want to use size macros), you can have `render` be just the URL, rather than a dictionary with `url` and `size`. * adComponents: (optional) A list of up to 20 adComponent strings from the InterestGroup's adComponents field. Each value must match one of `interestGroup`'s `adComponent`'s `renderUrl` and sizes exactly. This field must not be present if `interestGroup` has no `adComponent` field. It is valid for this field not to be present even when `adComponents` is present. (See ["Ads Composed of Multiple Pieces"](#34-ads-composed-of-multiple-pieces) below.) * allowComponentAuction: If this buyer is taking part of a component auction, this value must be present and true, or the bid is ignored. This value is ignored (and may be absent) if the buyer is part of a top-level auction. * modelingSignals: A 0-4095 integer (12-bits) passed to `reportWin()`, with noising, as described in the [noising and bucketing scheme](#521-noised-and-bucketed-signals). Invalid values, such as negative, infinite, and NaN values, will be ignored and not passed. Only the lowest 12 bits will be passed. From 7b856f74e3fe600ad46bdcceeb8836e8ccd51cfb Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 8 May 2023 12:38:15 -0400 Subject: [PATCH 40/60] Update FLEDGE.md Co-authored-by: Paul Jensen --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 59bafa595..98604e5a4 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -539,7 +539,7 @@ The arguments to `generateBid()` are: { 'topWindowHostname': 'www.example-publisher.com', 'seller': 'https://www.example-ssp.com', 'topLevelSeller': 'https://www.another-ssp.com', - 'requestedSize': {width: 100, height: 200}, + 'requestedSize': {width: 100, height: 200}, /* if specified in auction config */ 'joinCount': 3, 'bidCount': 17, 'prevWins': [[time1,ad1],[time2,ad2],...], From 0cc20cbe6d39f84bec3c2fd4aa478845c3c3947c Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 8 May 2023 12:39:00 -0400 Subject: [PATCH 41/60] Update Release_Notes.md Co-authored-by: Paul Jensen --- Release_Notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Release_Notes.md b/Release_Notes.md index 43c47f745..cc9e67d6a 100644 --- a/Release_Notes.md +++ b/Release_Notes.md @@ -8,7 +8,7 @@ ## Chrome M113 -* Support some of the size-related API changes (the ability to declare ad sizes in `joinAdInterestGroup`, include sizes with bids in `generateBid`, and have those sizes macro'd into the url with `AD_WIDTH` and `AD_HEIGHT` macros), in a backwards compatible and opt-in way. +* Support some of the size-related API changes (the ability to declare ad sizes in `joinAdInterestGroup`, include sizes with bids in `generateBid`, and have those sizes macro'd into the URL with `AD_WIDTH` and `AD_HEIGHT` macros), in a backwards compatible and opt-in way. ## Chrome M109 From 21795b98866bf1e3ce22d8df1c61f1c9c09739dd Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 8 May 2023 12:53:31 -0400 Subject: [PATCH 42/60] Update requestedSize description --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 98604e5a4..4ea998f9a 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -274,7 +274,7 @@ else This will cause the browser to execute the appropriate bidding and auction logic inside a collection of dedicated worklets associated with the buyer and seller domains. The `auctionSignals`, `sellerSignals`, and `perBuyerSignals` values will be passed as arguments to the appropriate functions that run inside those worklets — the `auctionSignals` are made available to everyone, while the other signals are given only to one party. -The optional `requestedSize` field recommends a frame size for the auction, which will be available to bidders in browser signals. Bidders inside the auction may pick a different size, but that resulting size will be scaled to fit inside the requested size. The returned fenced frame config will automatically populate a `` with the right size when loaded, unless the size is overridden with the element attributes. +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. 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). From ed3b8308f873734d769b6869acb6d288510fa5f7 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 8 May 2023 13:10:39 -0400 Subject: [PATCH 43/60] Update browser signals --- FLEDGE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 4ea998f9a..91640bcfc 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -346,6 +346,7 @@ The function gets called once for each candidate ad in the auction. The argumen { 'topWindowHostname': 'www.example-publisher.com', 'interestGroupOwner': 'https://www.example-dsp.com', 'renderUrl': 'https://cdn.com/render_url_of_bid', + 'renderSize': {width: 100, height: 200} /* if specified in the bid */ 'adComponents': ['https://cdn.com/ad_component_of_bid', 'https://cdn.com/next_ad_component_of_bid', ...], @@ -699,9 +700,10 @@ The arguments to this function are: { 'topWindowHostname': 'www.example-publisher.com', 'topLevelSeller': 'https://www.example-ssp.com', 'componentSeller': 'https://www.some-other-ssp.com', + 'requestedSize': {width: 100, height: 200}, /* if specified in the auction config */ 'interestGroupOwner': 'https://www.example-dsp.com/', 'renderUrl': 'https://cdn.com/url-of-winning-creative.wbn', - 'renderSize': {width: 100, height: 200}, + 'renderSize': {width: 100, height: 200}, /* if specified in the bid */ 'bid:' bidValue, 'desirability': desirabilityScoreForWinningAd, 'topLevelSellerSignals': outputOfTopLevelSellersReportResult, From cd737900cc9abac8976a3c800c17ea34d208e88e Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 8 May 2023 13:16:15 -0400 Subject: [PATCH 44/60] Update FLEDGE.md --- FLEDGE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 91640bcfc..bcbd01467 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -344,9 +344,10 @@ The function gets called once for each candidate ad in the auction. The argumen * browserSignals: An object constructed by the browser, containing information that the browser knows and which the seller's auction script might want to verify: ``` { 'topWindowHostname': 'www.example-publisher.com', + 'requestedSize': {width: 100, height: 200}, /* if specified in the bid */ 'interestGroupOwner': 'https://www.example-dsp.com', 'renderUrl': 'https://cdn.com/render_url_of_bid', - 'renderSize': {width: 100, height: 200} /* if specified in the bid */ + 'renderSize': {width: 100, height: 200}, /* if specified in the bid */ 'adComponents': ['https://cdn.com/ad_component_of_bid', 'https://cdn.com/next_ad_component_of_bid', ...], From 06ace1938243f1f909e0ca96daffb2d7a35f3373 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 26 May 2023 13:42:57 -0400 Subject: [PATCH 45/60] Change M115 to M116 for browser signals additions --- Release_Notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Release_Notes.md b/Release_Notes.md index cc9e67d6a..520a95482 100644 --- a/Release_Notes.md +++ b/Release_Notes.md @@ -3,7 +3,7 @@ ## Chrome M114 -* Support the ability to specify `requestedSize` in the auction config, which is eventually stored in the winning fenced frame config's container size. The `requestedSize` may not be accessible through browser signals in the auction until M115. +* Support the ability to specify `requestedSize` in the auction config, which is eventually stored in the winning fenced frame config's container size. The `requestedSize` may not be accessible through browser signals in the auction until M116, and is a lower priority because it is a convenience feature only (presumably the size of the ad slot is already passed in through other signals, if it is needed). ## Chrome M113 From ca80dd843b6a5b2710eaab1950c5af6f074d9dbb Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 9 Jun 2023 12:52:46 -0400 Subject: [PATCH 46/60] Fix "bid" -> "auction config" --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index bcbd01467..17772dbf6 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -344,7 +344,7 @@ The function gets called once for each candidate ad in the auction. The argumen * browserSignals: An object constructed by the browser, containing information that the browser knows and which the seller's auction script might want to verify: ``` { 'topWindowHostname': 'www.example-publisher.com', - 'requestedSize': {width: 100, height: 200}, /* if specified in the bid */ + 'requestedSize': {width: 100, height: 200}, /* if specified in the auction config */ 'interestGroupOwner': 'https://www.example-dsp.com', 'renderUrl': 'https://cdn.com/render_url_of_bid', 'renderSize': {width: 100, height: 200}, /* if specified in the bid */ From 910a9f278e09ec0a5afbefb874cb41b567cca1ea Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Mon, 12 Jun 2023 13:17:00 -0400 Subject: [PATCH 47/60] Remove renderSize from reportResult signals --- FLEDGE.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 17772dbf6..c8c56782e 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -704,7 +704,6 @@ The arguments to this function are: 'requestedSize': {width: 100, height: 200}, /* if specified in the auction config */ 'interestGroupOwner': 'https://www.example-dsp.com/', 'renderUrl': 'https://cdn.com/url-of-winning-creative.wbn', - 'renderSize': {width: 100, height: 200}, /* if specified in the bid */ 'bid:' bidValue, 'desirability': desirabilityScoreForWinningAd, 'topLevelSellerSignals': outputOfTopLevelSellersReportResult, @@ -717,7 +716,7 @@ The arguments to this function are: * sellerSignals: Like auctionConfig.sellerSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?sellerSignals`. * auctionSignals: Like auctionConfig.auctionSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?auctionSignals`. -The `browserSignals` argument must be handled carefully to avoid tracking. It certainly cannot include anything like the full list of interest groups, which would be too identifiable as a tracking signal. The `renderUrl` and `renderSize` can be included since they have already passed a k-anonymity check. The browser may limit the precision of the bid and desirability values by stochastically rounding them so that they fit into a floating point number with an 8 bit mantissa and 8 bit exponent to avoid these numbers exfiltrating information from the interest group's `userBiddingSignals`. On the upside, this set of signals can be expanded to include useful additional summary data about the wider range of bids that participated in the auction, e.g. the number of bids. Additionally, the `dataVersion` will only be present if the `Data-Version` header was provided in the response headers from the Trusted Scoring server. +The `browserSignals` argument must be handled carefully to avoid tracking. It certainly cannot include anything like the full list of interest groups, which would be too identifiable as a tracking signal. The `renderUrl` can be included since it has passed a k-anonymity check. Because `renderSize` will not be included in the k-anonymity check initially, it is not included in the browser signals. The browser may limit the precision of the bid and desirability values by stochastically rounding them so that they fit into a floating point number with an 8 bit mantissa and 8 bit exponent to avoid these numbers exfiltrating information from the interest group's `userBiddingSignals`. On the upside, this set of signals can be expanded to include useful additional summary data about the wider range of bids that participated in the auction, e.g. the number of bids. Additionally, the `dataVersion` will only be present if the `Data-Version` header was provided in the response headers from the Trusted Scoring server. The `reportResult()` function's reporting happens by directly calling network APIs in the short-term, but will eventually go through the Private Aggregation API once it has been developed. The output of this function is not used for reporting, but rather as an input to the buyer's reporting function. From b65b04a17d29146ef169e55304adfa6224dfa1ab Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 4 Aug 2023 13:03:43 -0400 Subject: [PATCH 48/60] Update FLEDGE.md --- FLEDGE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index c1f2319d7..701677d36 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -389,7 +389,6 @@ The function gets called once for each candidate ad in the auction. The argumen * browserSignals: An object constructed by the browser, containing information that the browser knows and which the seller's auction script might want to verify: ``` { 'topWindowHostname': 'www.example-publisher.com', - 'requestedSize': {width: 100, height: 200}, /* if specified in the auction config */ 'interestGroupOwner': 'https://www.example-dsp.com', 'renderURL': 'https://cdn.com/render_url_of_bid', 'renderSize': {width: 100, height: 200}, /* if specified in the bid */ From 4d4364b06414a0a556cc77f7a1bf43258684a6d4 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 4 Aug 2023 13:05:47 -0400 Subject: [PATCH 49/60] Update FLEDGE.md --- FLEDGE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 701677d36..4dfc21fe7 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -746,7 +746,6 @@ The arguments to this function are: { 'topWindowHostname': 'www.example-publisher.com', 'topLevelSeller': 'https://www.example-ssp.com', 'componentSeller': 'https://www.some-other-ssp.com', - 'requestedSize': {width: 100, height: 200}, /* if specified in the auction config */ 'interestGroupOwner': 'https://www.example-dsp.com/', 'renderURL': 'https://cdn.com/url-of-winning-creative.wbn', 'bid:' bidValue, From 6e6ec8563bf0be1b146a298855cf4bcd226f69a8 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 8 Aug 2023 13:44:10 -0400 Subject: [PATCH 50/60] Update FLEDGE.md Co-authored-by: Paul Jensen --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 4dfc21fe7..a41a55a67 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -220,7 +220,7 @@ same-origin with `owner` and must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources. -The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). (Note: for a transition period, in the implementation, the size is excluded from the k-anonymity check even when specified by `generateBid`.) For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized ad that is still below the k-anonymity threshold could still choose to participate in auctions, and its interest group has a way to fall back to a more generic ad until the more specialized one has a large enough audience. +The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and eventually after a transition period the size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized ad that is still below the k-anonymity threshold could still choose to participate in auctions, and its interest group has a way to fall back to a more generic ad until the more specialized one has a large enough audience. #### 1.3 Permission Delegation From 975e9651db009c4789135eeb9b3ba5f118c1ec61 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Tue, 8 Aug 2023 13:45:39 -0400 Subject: [PATCH 51/60] Fix rebase issue --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index a41a55a67..6e5bc07fd 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -604,7 +604,7 @@ The output of `generateBid()` contains the following fields: * ad: (optional) Arbitrary metadata about the ad which this interest group wants to show. The seller uses this information in its auction and decision logic. If not present, it's treated as if the value were null. * adCost: (optional) A numerical value used to pass reporting advertiser click or conversion cost from generateBid to reportWin. The precision of this number is limited to an 8-bit mantissa and 8-bit exponent, with any rounding performed stochastically. -* bid: A numerical bid that will enter the auction. The seller must be in a position to compare bids from different buyers, therefore bids must be in some seller-chosen unit (e.g. "USD per thousand"). If the bid is zero or negative, then this interest group will not participate in the seller's auction at all. With this mechanism, the buyer can implement any advertiser rules for where their ads may or may not appear. +* bid: A numerical bid that will enter the auction. The seller must be in a position to compare bids from different buyers, therefore bids must be in some seller-chosen unit (e.g. "USD per thousand"). If the bid is zero or negative, then this interest group will not participate in the seller's auction at all. With this mechanism, the buyer can implement any advertiser rules for where their ads may or may not appear. While this returned value is expected to be a JavaScript Number, internal calculations dealing with currencies should be done with integer math that more accurately represent powers of ten. * render: A dictionary describing the creative that should be rendered if this bid wins the auction. This includes: * url: The creative's URL. * size: A dictionary containing `width` and `height` fields, describing the creative's size (see the interest group declaration above). When the ad is loaded in a fenced frame, the fenced frame's inner frame (i.e. the size visible to the ad creative) will be frozen to this size, and it will be unable to see changes to the frame size made by the embedder. From c3fad7abd252a50ac58046dc2db6aef83eba511a Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 1 Sep 2023 15:35:45 -0400 Subject: [PATCH 52/60] Add extra macro format --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 6e5bc07fd..1fb551f68 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -211,7 +211,7 @@ The `adSizes` field (optionally) contains a dictionary of named ad sizes. Each s The `sizeGroups` field (optionally) contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -In the future, when the sizes are declared, the URL-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Note: for a transition period, in the implementation, only the URL is used for k-anonymity checks, not the size.) Then once an ad with a particular size wins the auction, the size will be substituted into any macros in the URL (see note on `{%AD_WIDTH%}` and `{%AD_HEIGHT%}` above), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. +In the future, when the sizes are declared, the URL-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Note: for a transition period, in the implementation, only the URL is used for k-anonymity checks, not the size.) When an ad with a particular size wins the auction (including in the current implementation), the size will be substituted into any macros in the URL (through `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, or `${AD_WIDTH}` and `${AD_HEIGHT}`), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable. All fields that specify URLs for loading scripts or JSON (`biddingLogicURL`, From cce7780fcc83292a30da2cb6b8441c68fc345e84 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Fri, 1 Sep 2023 15:47:53 -0400 Subject: [PATCH 53/60] Fix {size: ...} --- FLEDGE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 1fb551f68..6a908868f 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -562,9 +562,9 @@ generateBid(interestGroup, auctionSignals, perBuyerSignals, return {'ad': adObject, 'adCost': optionalAdCost, 'bid': bidValue, - 'render': {url: renderURL, size: {width: renderWidth, height: renderHeight}}, - 'adComponents': [{url: adComponent1, size: {width: componentWidth1, height: componentHeight1}}, - {url: adComponent2, size: {width: componentWidth2, height: componentHeight2}}, ...], + 'render': {url: renderURL, width: renderWidth, height: renderHeight}, + 'adComponents': [{url: adComponent1, width: componentWidth1, height: componentHeight1}, + {url: adComponent2, width: componentWidth2, height: componentHeight2}, ...], 'allowComponentAuction': false, 'modelingSignals': 123}; } From a3662d5107cdd672273e93fcaa788ae81ee40f95 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Thu, 26 Oct 2023 10:29:25 -0400 Subject: [PATCH 54/60] Add explicit transition period --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index f4a6e324e..f6ac6a34d 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -225,7 +225,7 @@ The `adSizes` field (optionally) contains a dictionary of named ad sizes. Each s The `sizeGroups` field (optionally) contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -In the future, when the sizes are declared, the URL-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Note: for a transition period, in the implementation, only the URL is used for k-anonymity checks, not the size.) When an ad with a particular size wins the auction (including in the current implementation), the size will be substituted into any macros in the URL (through `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, or `${AD_WIDTH}` and `${AD_HEIGHT}`), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. +In the future, when the sizes are declared, the URL-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Note: until [Q1 2025](https://developer.chrome.com/docs/privacy-sandbox/protected-audience-api/feature-status/#k-anonymity), in the implementation, only the URL is used for k-anonymity checks, not the size.) When an ad with a particular size wins the auction (including in the current implementation), the size will be substituted into any macros in the URL (through `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, or `${AD_WIDTH}` and `${AD_HEIGHT}`), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. The `auctionServerRequestFlags` field is optional and is only used for auctions [run on an auction server](https://github.com/WICG/turtledove/blob/main/FLEDGE_browser_bidding_and_auction_API.md). This field contains a list of enumerated values that change what data is sent in the auction blob: From d69f23309de2b2a92672de197fee53b5db7b2239 Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Thu, 26 Oct 2023 10:30:39 -0400 Subject: [PATCH 55/60] Add explicit transition period --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index f6ac6a34d..490a33c92 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -866,7 +866,7 @@ The arguments to this function are: * sellerSignals: The output of `reportResult()` above, giving the seller an opportunity to pass information to the buyer. In the case where the winning buyer won a component auction and then went on to win the top-level auction, this is the output of component auction's seller's `reportResult()` method. * browserSignals: Similar to the argument to `reportResult()` above, though without the seller's desirability score, but with additional `adCost`, `seller`, `madeHighestScoringOtherBid` and potentially `interestGroupName` fields: * The `adCost` field contains the value that was returned by `generateBid()`, stochastically rounded to fit into a floating point number with an 8 bit mantissa and 8 bit exponent. This field is only present if `adCost` was returned by `generateBid()`. - * The `interestGroupName` may be included if the tuple of interest group owner, name, bidding script URL, ad creative URL, and ad creative size (if specified by `generateBid`) were jointly k-anonymous. (Note: for a transition period, in the implementation, the ad creative size is excluded from this check.) + * The `interestGroupName` may be included if the tuple of interest group owner, name, bidding script URL, ad creative URL, and ad creative size (if specified by `generateBid`) were jointly k-anonymous. (Note: until [Q1 2025](https://developer.chrome.com/docs/privacy-sandbox/protected-audience-api/feature-status/#k-anonymity), in the implementation, the ad creative size is excluded from this check.) * The `madeHighestScoringOtherBid` field is true if the interest group owner was the only bidder that made bids with the second highest score. * The `highestScoringOtherBid` and `madeHighestScoringOtherBid` fields are based on the auction the interest group was directly part of. If that was a component auction, they're from the component auction. If that was the top-level auction, then they're from the top-level auction. Component bidders do not get these signals from top-level auctions since it is the auction seller joining the top-level auction, instead of winning component bidders joining the top-level auction directly. * The `dataVersion` field will contain the `Data-Version` from the trusted bidding signals response headers if they were provided by the trusted bidding signals server response and the version was consistent for all keys requested by this interest group, otherwise the field will be absent. From 2d3f228dcc2d3aefd88baff32e563a70f286dd8c Mon Sep 17 00:00:00 2001 From: Garrett Tanzer Date: Thu, 26 Oct 2023 10:33:24 -0400 Subject: [PATCH 56/60] Add explicit transition period --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 490a33c92..2d514d87a 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -243,7 +243,7 @@ same-origin with `owner` and must point to URLs whose responses include the HTTP response header `Ad-Auction-Allowed: true` to ensure they are allowed to be used for loading Protected Audience resources. -The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 50 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, Protected Audience has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and eventually after a transition period the size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized ad that is still below the k-anonymity threshold could still choose to participate in auctions, and its interest group has a way to fall back to a more generic ad until the more specialized one has a large enough audience. +The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 50 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, Protected Audience has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and after [Q1 2025](https://developer.chrome.com/docs/privacy-sandbox/protected-audience-api/feature-status/#k-anonymity) the size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized ad that is still below the k-anonymity threshold could still choose to participate in auctions, and its interest group has a way to fall back to a more generic ad until the more specialized one has a large enough audience. #### 1.3 Permission Delegation From a57adbee2198570351fcc0226be6f95e9b9975c8 Mon Sep 17 00:00:00 2001 From: Paul Jensen Date: Mon, 30 Oct 2023 16:29:44 -0400 Subject: [PATCH 57/60] Update FLEDGE.md Co-authored-by: Alonso Velasquez <114112643+ajvelasquezgoog@users.noreply.github.com> --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 2d514d87a..3a7b4cc9c 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -225,7 +225,7 @@ The `adSizes` field (optionally) contains a dictionary of named ad sizes. Each s The `sizeGroups` field (optionally) contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -In the future, when the sizes are declared, the URL-size pairings will be used to prefetch k-anonymity checks, which limit the configurations that can win an auction. (Note: until [Q1 2025](https://developer.chrome.com/docs/privacy-sandbox/protected-audience-api/feature-status/#k-anonymity), in the implementation, only the URL is used for k-anonymity checks, not the size.) When an ad with a particular size wins the auction (including in the current implementation), the size will be substituted into any macros in the URL (through `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, or `${AD_WIDTH}` and `${AD_HEIGHT}`), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. +At some point in the future - no earlier than Q12025 - when the sizes are declared, the URL-size pairings will be used to prefetch k-anonymity checks to limit the configurations that can win an auction (please see(https://developer.chrome.com/docs/privacy-sandbox/protected-audience-api/feature-status/#k-anonymity. In the present implementation, only the URL is used for k-anonymity checks, not the size). When an ad with a particular size wins the auction (including in the current implementation), the size will be substituted into any macros in the URL (through `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, or `${AD_WIDTH}` and `${AD_HEIGHT}`), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. The `auctionServerRequestFlags` field is optional and is only used for auctions [run on an auction server](https://github.com/WICG/turtledove/blob/main/FLEDGE_browser_bidding_and_auction_API.md). This field contains a list of enumerated values that change what data is sent in the auction blob: From 7148d74060d530b1df5f8d52fd794c495026f57d Mon Sep 17 00:00:00 2001 From: Paul Jensen Date: Mon, 30 Oct 2023 16:33:30 -0400 Subject: [PATCH 58/60] Fix link and perens. --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 3a7b4cc9c..7f093b29a 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -225,7 +225,7 @@ The `adSizes` field (optionally) contains a dictionary of named ad sizes. Each s The `sizeGroups` field (optionally) contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -At some point in the future - no earlier than Q12025 - when the sizes are declared, the URL-size pairings will be used to prefetch k-anonymity checks to limit the configurations that can win an auction (please see(https://developer.chrome.com/docs/privacy-sandbox/protected-audience-api/feature-status/#k-anonymity. In the present implementation, only the URL is used for k-anonymity checks, not the size). When an ad with a particular size wins the auction (including in the current implementation), the size will be substituted into any macros in the URL (through `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, or `${AD_WIDTH}` and `${AD_HEIGHT}`), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. +At some point in the future - no earlier than Q12025 - when the sizes are declared, the URL-size pairings will be used to prefetch k-anonymity checks to limit the configurations that can win an auction, please see [this doc](https://developer.chrome.com/docs/privacy-sandbox/protected-audience-api/feature-status/#k-anonymity). In the present implementation, only the URL is used for k-anonymity checks, not the size. When an ad with a particular size wins the auction (including in the current implementation), the size will be substituted into any macros in the URL (through `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, or `${AD_WIDTH}` and `${AD_HEIGHT}`), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. The `auctionServerRequestFlags` field is optional and is only used for auctions [run on an auction server](https://github.com/WICG/turtledove/blob/main/FLEDGE_browser_bidding_and_auction_API.md). This field contains a list of enumerated values that change what data is sent in the auction blob: From f8cd3f6d3663850ba6435981a851015ad56a7b2b Mon Sep 17 00:00:00 2001 From: Paul Jensen Date: Tue, 31 Oct 2023 11:33:53 -0400 Subject: [PATCH 59/60] Update FLEDGE.md Co-authored-by: Alonso Velasquez <114112643+ajvelasquezgoog@users.noreply.github.com> --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 7f093b29a..984138361 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -243,7 +243,7 @@ same-origin with `owner` and must point to URLs whose responses include the HTTP response header `Ad-Auction-Allowed: true` to ensure they are allowed to be used for loading Protected Audience resources. -The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 50 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, Protected Audience has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and after [Q1 2025](https://developer.chrome.com/docs/privacy-sandbox/protected-audience-api/feature-status/#k-anonymity) the size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized ad that is still below the k-anonymity threshold could still choose to participate in auctions, and its interest group has a way to fall back to a more generic ad until the more specialized one has a large enough audience. +The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 50 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, Protected Audience has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (URL, and [no earlier than Q1 2025](https://developer.chrome.com/docs/privacy-sandbox/protected-audience-api/feature-status/#k-anonymity) the size if specified by `generateBid`) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized ad that is still below the k-anonymity threshold could still choose to participate in auctions, and its interest group has a way to fall back to a more generic ad until the more specialized one has a large enough audience. #### 1.3 Permission Delegation From 50893b4c778e40beff9c43b024a3a868cb89d8e8 Mon Sep 17 00:00:00 2001 From: Paul Jensen Date: Tue, 31 Oct 2023 11:37:24 -0400 Subject: [PATCH 60/60] add missing space --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 984138361..c1e470b16 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -225,7 +225,7 @@ The `adSizes` field (optionally) contains a dictionary of named ad sizes. Each s The `sizeGroups` field (optionally) contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at. Each named ad size is also considered a size group, so you don't need to manually define singleton size groups; for example see the `sizeGroup: 'size3'` code above. -At some point in the future - no earlier than Q12025 - when the sizes are declared, the URL-size pairings will be used to prefetch k-anonymity checks to limit the configurations that can win an auction, please see [this doc](https://developer.chrome.com/docs/privacy-sandbox/protected-audience-api/feature-status/#k-anonymity). In the present implementation, only the URL is used for k-anonymity checks, not the size. When an ad with a particular size wins the auction (including in the current implementation), the size will be substituted into any macros in the URL (through `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, or `${AD_WIDTH}` and `${AD_HEIGHT}`), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. +At some point in the future - no earlier than Q1 2025 - when the sizes are declared, the URL-size pairings will be used to prefetch k-anonymity checks to limit the configurations that can win an auction, please see [this doc](https://developer.chrome.com/docs/privacy-sandbox/protected-audience-api/feature-status/#k-anonymity). In the present implementation, only the URL is used for k-anonymity checks, not the size. When an ad with a particular size wins the auction (including in the current implementation), the size will be substituted into any macros in the URL (through `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, or `${AD_WIDTH}` and `${AD_HEIGHT}`), and once loaded into a fenced frame, the size will be used by the browser to freeze the fenced frame's inner dimensions. We therefore recommend using ad size declarations, but they are not required at this time. The `auctionServerRequestFlags` field is optional and is only used for auctions [run on an auction server](https://github.com/WICG/turtledove/blob/main/FLEDGE_browser_bidding_and_auction_API.md). This field contains a list of enumerated values that change what data is sent in the auction blob: