From c20ae4ceeacd74e51507a4e687abaf608720fbc8 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 21 Jul 2022 14:22:29 -0400 Subject: [PATCH 01/27] Update FLEDGE.md --- FLEDGE.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/FLEDGE.md b/FLEDGE.md index 224c2cc42..9628041b6 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -24,6 +24,7 @@ We plan to hold regular meetings under the auspices of the WICG to go through th - [3.2 On-Device Bidding](#32-on-device-bidding) - [3.3 Metadata with the Ad Bid](#33-metadata-with-the-ad-bid) - [3.4 Ads Composed of Multiple Pieces](#34-ads-composed-of-multiple-pieces) + - [3.5 Prioritizing Interest Groups](#35-prioritizing-interest-groups) - [4. Browsers Render the Winning Ad](#4-browsers-render-the-winning-ad) - [5. Event-Level Reporting (for now)](#5-event-level-reporting-for-now) - [5.1 Seller Reporting on Render](#51-seller-reporting-on-render) @@ -88,6 +89,17 @@ const myGroup = { 'owner': 'https://www.example-dsp.com', 'name': 'womens-running-shoes', 'priority': 0.0, + 'priorityVector': { + 'signal1': 2, + 'signal2': -3.5, + ... + } + 'prioritySignalsOverrides': { + 'signal1': 4.5, + 'signal2': 0, + ... + } + `enableBiddingSignalsPrioritization` : [true | false], 'biddingLogicUrl': ..., 'biddingWasmHelperUrl': ..., 'dailyUpdateUrl': ..., @@ -114,6 +126,10 @@ The browser will remain in an interest group for only a limited amount of time. The `priority` is used to select which interest groups participate in an auction when the number of interest groups are limited by the `perBuyerGroupLimits` attribute of the auction config. If not specified, a `priority` of `0.0` is assigned. There is no special meaning to these values. These values are only used to select interest groups to participate in an auction such that if there is an interest group participating in the auction with priority `x`, all interest groups with the same owner having a priority `y` where `y > x` should also participate (i.e. `generateBid` will be called). In the case where some but not all interest groups with equal priority can participate in an auction due to `perBuyerGroupLimits`, the participating interest groups will be uniformly randomly chosen from the set of interest groups with that priority. +`priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization`, are optional values use to dymnically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while enableBiddingSignalsPrioritization is a bool that defaults to false. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for a description of these fields. + +`prioritySignalsOverrides` is an optional mapping of string keys to Javascript numbers that, if present, will override the corresponding values in a `prioritySignals` vector when using a `priorityVector` to calculate an interest group's priority. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. + The `userBiddingSignals` is for storage of additional metadata that the owner can use during on-device bidding, and the `trustedBiddingSignals` attributes provide another mechanism for making real-time data available for use at bidding time. The `biddingWasmHelperUrl` field is optional, and lets the bidder provide computationally-expensive subroutines in WebAssembly, rather than JavaScript, to be driven from the JavaScript function provided by `biddingLogicUrl`. If provided, it must point to a WebAssembly binary, delivered with an `application/wasm` mimetype. The corresponding `WebAssembly.Module` will be made available by the browser to the `generateBid` function. @@ -183,6 +199,13 @@ const myAuctionConfig = { 'https://www.another-buyer.com': 1000, '*': 15, ...}, + 'perBuyerPrioritySignals': {'https://www.example-dsp.com': { + 'signal1': 2.5, + 'signal2': 2.5, + ...}, + 'https://www.another-buyer.com': {...}, + '*': {...}, + ...}, 'componentAuctions': [ {'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., @@ -204,6 +227,8 @@ Optionally, `sellerTimeout` can be specified to restrict the runtime (in millise Optionally, `perBuyerGroupLimits` can be specified to limit the number of of interest groups from a particular buyer that participate in the auction. A key of `'*'` in `perBuyerGroupLimits` is used to set a limit for unspecified buyers. For each buyer, interest groups will be selected to participate in the auction in order of decreasing `priority` (larger priorities are selected first) up to the specfied limit. The selection of interest groups occurs independently for each buyer, so the priorities do not need to be comparable between buyers and could have a buyer-specific meaning. The value of the limits provided should be able to be represented by a 16 bit unsigned integer. +Optionally, `perBuyerPrioritySignals` is an object mapping string keys to Javascript numbers that can be used to dynamically compute interest group priorities at the start of the auction, before perBuyerGroupLimits are applied. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. + All fields that accept arbitrary metadata objects (`auctionSignals`, `sellerSignals`, and keys of `perBuyerSignals`) must be JSON-serializable. A `Permissions-Policy` directive named "run-ad-auction" controls access to the `navigator.runAdAuction()` API. From 599f748ceaa0c584acbd8c199037823743179449 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 21 Jul 2022 15:59:22 -0400 Subject: [PATCH 02/27] Update FLEDGE.md --- FLEDGE.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 9628041b6..13546bc37 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -128,8 +128,6 @@ The `priority` is used to select which interest groups participate in an auction `priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization`, are optional values use to dymnically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while enableBiddingSignalsPrioritization is a bool that defaults to false. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for a description of these fields. -`prioritySignalsOverrides` is an optional mapping of string keys to Javascript numbers that, if present, will override the corresponding values in a `prioritySignals` vector when using a `priorityVector` to calculate an interest group's priority. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. - The `userBiddingSignals` is for storage of additional metadata that the owner can use during on-device bidding, and the `trustedBiddingSignals` attributes provide another mechanism for making real-time data available for use at bidding time. The `biddingWasmHelperUrl` field is optional, and lets the bidder provide computationally-expensive subroutines in WebAssembly, rather than JavaScript, to be driven from the JavaScript function provided by `biddingLogicUrl`. If provided, it must point to a WebAssembly binary, delivered with an `application/wasm` mimetype. The corresponding `WebAssembly.Module` will be made available by the browser to the `generateBid` function. @@ -401,6 +399,7 @@ The arguments to `generateBid()` are: * interestGroup: The interest group object, as saved during `joinAdInterestGroup()` and perhaps updated via the `dailyUpdateUrl`. + * `priority` and `prioritySignalsOverrides` are not included. The can be modified by generatedBid() calls, so could theoretically be used to create a cross-site profile of a user by adding data when an interest group participates in an auction, so are not included. * auctionSignals: As provided by the seller in the call to `runAdAuction()`. This is the opportunity for the seller to provide information about the page context (ad size, publisher ID, etc), the type of auction (first-price vs second-price), and so on. * perBuyerSignals: The value for _this specific buyer_ as taken from the auction config passed to `runAdAuction()`. This can include contextual signals about the page that come from the buyer's server, if the seller is an SSP which performs a real-time bidding call to buyer servers and pipes the response back, or if the publisher page contacts the buyer's server directly. If so, the buyer may wish to check a cryptographic signature of those signals inside `generateBid()` as protection against tampering. * trustedBiddingSignals: An object whose keys are the `trustedBiddingSignalsKeys` for the interest group, and whose values are those returned in the `trustedBiddingSignals` request. @@ -444,6 +443,30 @@ The [Product-level TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/PR The output of `generateBid()` can use the on-device ad composition flow through an optional adComponents field, listing additional URLs made available to the fenced frame the container URL is loaded in. The component URLs may be retrieved by calling `navigator.adAuctionComponents(numComponents)`, where numComponents is at most 20. To prevent bidder worklets from using this as a sidechannel to leak additional data to the fenced frame, exactly numComponents obfuscated URLs will be returned by this method, regardless of how many adComponent URLs were actually in the bid, even if the bid contained no adComponents, and the Interest Group itself had no adComponents either. +#### 3.5 Prioritizing Interest Groups + +When an InterestGroup has a non-empty `priorityVector`, its priority is dynically calculted before applying `perBuyerGroupLimits`. To do this, the sparse dot product of interest group's `priorityVector` is multiplied by a `prioritySignals` vector. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entry in objects earlier in the list taking priority over entries later in the list: + +* The interest group's `prioritySignalsOverrides` field. +* A browser-generated `prioritySignals` object, defined below. +* The `auctionConfig`'s `perBuyerPrioritySignals` entry for the interest group owner. +* The `auctionConfig`'s `perBuyerPrioritySignals` "\*" entry. + +Additionally, keys starting with "browserSignals." are reserved, and may only appear in `prioritySignalsOverrides` and the browser-generated `prioritySignals` object. + +The browser-generated `prioritySignals` object contains the following values: +* `browserSignals.one`: This is always 1. It's useful for adding a constant to the dot product. +* `browserSignals.age`: How long ago the user was added to the interest group, in milliseconds. This is the most recent time the use was added to the injterest group, so re-joining an interest group resets the value. This value is always non-negative. +* `browserSignals.basePriority`: The priority field in the interest group, which may have been modified by a setPriority() call. +* `browserSignals.firstDotProductPriority`: The priority from multiplying the interest group's `priorityVector` by `prioritySignals`. Only non-zero when using a `proirityVector` from a trusted bidding signals fetch, and the interest group also has a `prioritySignals` field. See below for more details. + +If the resulting dot-product is negative, the interest group is immediately removed from an auction (Note that if there's no `priorityVector`, interest groups with negative values currently are not filtered from auctions). After calculting new priorities, as needed, and filtering out interest groups with negative calculated priorities, the `perBuyerGroupLimits` value is applied to all interest groups of a given order, unless the interest group's `enableBiddingSignalsPrioritization` field is present and true. + +If `enableBiddingSignalsPrioritization` is true, then rather than applying `perBuyerGroupLimits` immediately after the the calculating the sparse dot product as desribed above (if `priorityVector` is non-null), then instead, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is a again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that it may have a non-zero `browserSignals.firstDotProductPriority` value. If this dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. + +The advantage of having not using `enableBiddingSignalsPrioritization` is that interest groups can be filtered out before bidding signals are fetched. In auctions with large numbers of buyers auctions, some buyers may also be able to filter themselves out entirely, which could significantly improve performance. + + ### 4. Browsers Render the Winning Ad The winning ad will be rendered in a [Fenced Frame](https://github.com/shivanigithub/fenced-frame): a mechanism under development for rendering a document in an embedded context which is unable to communicate with the surrounding page. This communication blockage is necessary to meet the privacy goal that sites cannot learn about their visitors' ad interests. (Note that the microtargeting prevention threshold alone is not enough to address this threat: the threshold prevents ads which could identify a single person, but it allows ads which identify a group of people that share a single interest.) From d4eeaa8fd8bac4328ea8a223b82eca965cb4af4b Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 21 Jul 2022 16:16:35 -0400 Subject: [PATCH 03/27] Update FLEDGE.md --- FLEDGE.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 13546bc37..e41a74030 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -126,7 +126,7 @@ The browser will remain in an interest group for only a limited amount of time. The `priority` is used to select which interest groups participate in an auction when the number of interest groups are limited by the `perBuyerGroupLimits` attribute of the auction config. If not specified, a `priority` of `0.0` is assigned. There is no special meaning to these values. These values are only used to select interest groups to participate in an auction such that if there is an interest group participating in the auction with priority `x`, all interest groups with the same owner having a priority `y` where `y > x` should also participate (i.e. `generateBid` will be called). In the case where some but not all interest groups with equal priority can participate in an auction due to `perBuyerGroupLimits`, the participating interest groups will be uniformly randomly chosen from the set of interest groups with that priority. -`priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization`, are optional values use to dymnically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while enableBiddingSignalsPrioritization is a bool that defaults to false. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for a description of these fields. +`priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization`, are optional values use to dymnically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while enableBiddingSignalsPrioritization is a bool that defaults to `false`. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for a description of these fields. The `userBiddingSignals` is for storage of additional metadata that the owner can use during on-device bidding, and the `trustedBiddingSignals` attributes provide another mechanism for making real-time data available for use at bidding time. @@ -325,9 +325,9 @@ Buyers have three basic jobs in the on-device ad auction: Buyers may want to make on-device decisions that take into account real-time data (for example, the remaining budget of an ad campaign). This need can be met using the interest group's `trustedBiddingSignalsUrl` and `trustedBiddingSignalsKeys` fields. Once a seller initiates an on-device auction on a publisher page, the browser checks each participating interest group for these fields, and makes an uncredentialed (cookieless) HTTP fetch to a URL of the form: - https://www.kv-server.example/getvalues?hostname=publisher.com&keys=key1,key2 + https://www.kv-server.example/getvalues?hostname=publisher.com&keys=key1,key2&interestGroups=name1,name2 -The base URL `https://www.kv-server.example/getvalues` comes from the interest group's `trustedBiddingSignalsUrl`, the hostname of the top-level webpage where the ad will appear `publisher.com` is provided by the browser, and `keys` is a list of `trustedBiddingSignalsKeys` strings. The requests may be coalesced (for efficiency) across any number of interest groups that share a `trustedBiddingSignalsUrl` (which means they also share an owner). +The base URL `https://www.kv-server.example/getvalues` comes from the interest group's `trustedBiddingSignalsUrl`, the hostname of the top-level webpage where the ad will appear `publisher.com` is provided by the browser, `keys` is a list of `trustedBiddingSignalsKeys` strings, and interestGroupNames is a list of the names of interest groups data is being fetched for. The requests may be coalesced (for efficiency) across any number of interest groups that share a `trustedBiddingSignalsUrl` (which means they also share an owner). The response from the server should be a JSON object of the form: @@ -335,13 +335,24 @@ The response from the server should be a JSON object of the form: { 'keys': { 'key1': arbitrary_json, 'key2': arbitrary_json, - ...} + ...}, + 'perInterestGroupData': { + 'name1': { + 'priorityVector': { + 'signal1': number, + 'signal2': number, + ...} + }, + ... + } } ``` and the server must include the HTTP response header `X-fledge-bidding-signals-format-version: 2`. If the server does not include the header, the response will assumed to be an in older format, where the response is only the contents of the `keys` dictionary. -The value of each key that an interest group has in its `trustedBiddingSignalsKeys` list will be passed to the interest group's generateBid() function as the `trustedBiddingSignals` parameter. Values missing from the JSON object will be set to null. If the JSON download fails, or there are no `trustedBiddingSignalsKeys` or `trustedBiddingSignalsUrl` in the interest group, then the `trustedBiddingSignals` argument to generateBid() will be null. +The value of each key that an interest group has in its `trustedBiddingSignalsKeys` list will be passed from the `keys` dictionary to the interest group's generateBid() function as the `trustedBiddingSignals` parameter. Values missing from the JSON object will be set to null. If the JSON download fails, or there are no `trustedBiddingSignalsKeys` or `trustedBiddingSignalsUrl` in the interest group, then the `trustedBiddingSignals` argument to generateBid() will be null. + +The `perInterestGroupData` dictionary contains optional data for interest groups whose names were included in the request URL. The `priorityVector` will be used as the priority for an interest group, if that interest group has `enableBiddingSignalsPrioritization` set to `true` in its definition. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. Similarly, sellers may want to fetch information about a specific creative, e.g. the results of some out-of-band ad scanning system. This works in much the same way, with the base URL coming from the `trustedScoringSignalsUrl` property of the seller's auction configuration object. However, it has two sets of keys: "renderUrls=url1,url2,..." and "adComponentRenderUrls=url1,url2,..." for the main and adComponent renderUrls bids offered in the auction. It is up to the client how and whether to aggregate the fetches with the URLs of multiple bidders. The response to this request should be in the form: @@ -462,7 +473,7 @@ The browser-generated `prioritySignals` object contains the following values: If the resulting dot-product is negative, the interest group is immediately removed from an auction (Note that if there's no `priorityVector`, interest groups with negative values currently are not filtered from auctions). After calculting new priorities, as needed, and filtering out interest groups with negative calculated priorities, the `perBuyerGroupLimits` value is applied to all interest groups of a given order, unless the interest group's `enableBiddingSignalsPrioritization` field is present and true. -If `enableBiddingSignalsPrioritization` is true, then rather than applying `perBuyerGroupLimits` immediately after the the calculating the sparse dot product as desribed above (if `priorityVector` is non-null), then instead, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is a again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that it may have a non-zero `browserSignals.firstDotProductPriority` value. If this dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. +If `enableBiddingSignalsPrioritization` is `true`, then rather than applying `perBuyerGroupLimits` immediately after the the calculating the sparse dot product as desribed above (if `priorityVector` is non-null), then instead, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is a again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that it may have a non-zero `browserSignals.firstDotProductPriority` value. If this dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. The advantage of having not using `enableBiddingSignalsPrioritization` is that interest groups can be filtered out before bidding signals are fetched. In auctions with large numbers of buyers auctions, some buyers may also be able to filter themselves out entirely, which could significantly improve performance. From 8b2b71e954a85913ca978b84f6049ed3e785b699 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 21 Jul 2022 16:18:25 -0400 Subject: [PATCH 04/27] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index e41a74030..8e621336b 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -126,7 +126,7 @@ The browser will remain in an interest group for only a limited amount of time. The `priority` is used to select which interest groups participate in an auction when the number of interest groups are limited by the `perBuyerGroupLimits` attribute of the auction config. If not specified, a `priority` of `0.0` is assigned. There is no special meaning to these values. These values are only used to select interest groups to participate in an auction such that if there is an interest group participating in the auction with priority `x`, all interest groups with the same owner having a priority `y` where `y > x` should also participate (i.e. `generateBid` will be called). In the case where some but not all interest groups with equal priority can participate in an auction due to `perBuyerGroupLimits`, the participating interest groups will be uniformly randomly chosen from the set of interest groups with that priority. -`priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization`, are optional values use to dymnically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while enableBiddingSignalsPrioritization is a bool that defaults to `false`. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for a description of these fields. +`priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization` are optional values used to dymnically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while enableBiddingSignalsPrioritization is a bool that defaults to `false`. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for a description of how these fields are used. The `userBiddingSignals` is for storage of additional metadata that the owner can use during on-device bidding, and the `trustedBiddingSignals` attributes provide another mechanism for making real-time data available for use at bidding time. From 893e83795b1806f98fa806568338bfa73e6025e6 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 21 Jul 2022 16:26:24 -0400 Subject: [PATCH 05/27] Update FLEDGE.md --- FLEDGE.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 8e621336b..806c2f901 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -194,13 +194,12 @@ const myAuctionConfig = { '*': 150, ...}, 'perBuyerGroupLimits': {'https://www.example-dsp.com': 2, - 'https://www.another-buyer.com': 1000, - '*': 15, - ...}, - 'perBuyerPrioritySignals': {'https://www.example-dsp.com': { - 'signal1': 2.5, - 'signal2': 2.5, - ...}, + 'https://www.another-buyer.com': 1000, + '*': 15, + ...}, + 'perBuyerPrioritySignals': {'https://www.example-dsp.com': {'signal1': 2.5, + 'signal2': 2.5, + ...}, 'https://www.another-buyer.com': {...}, '*': {...}, ...}, @@ -225,7 +224,7 @@ Optionally, `sellerTimeout` can be specified to restrict the runtime (in millise Optionally, `perBuyerGroupLimits` can be specified to limit the number of of interest groups from a particular buyer that participate in the auction. A key of `'*'` in `perBuyerGroupLimits` is used to set a limit for unspecified buyers. For each buyer, interest groups will be selected to participate in the auction in order of decreasing `priority` (larger priorities are selected first) up to the specfied limit. The selection of interest groups occurs independently for each buyer, so the priorities do not need to be comparable between buyers and could have a buyer-specific meaning. The value of the limits provided should be able to be represented by a 16 bit unsigned integer. -Optionally, `perBuyerPrioritySignals` is an object mapping string keys to Javascript numbers that can be used to dynamically compute interest group priorities at the start of the auction, before perBuyerGroupLimits are applied. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. +Optionally, `perBuyerPrioritySignals` is an object mapping string keys to Javascript numbers that can be used to dynamically compute interest group priorities before perBuyerGroupLimits are applied. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. All fields that accept arbitrary metadata objects (`auctionSignals`, `sellerSignals`, and keys of `perBuyerSignals`) must be JSON-serializable. @@ -456,7 +455,7 @@ The output of `generateBid()` can use the on-device ad composition flow through #### 3.5 Prioritizing Interest Groups -When an InterestGroup has a non-empty `priorityVector`, its priority is dynically calculted before applying `perBuyerGroupLimits`. To do this, the sparse dot product of interest group's `priorityVector` is multiplied by a `prioritySignals` vector. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entry in objects earlier in the list taking priority over entries later in the list: +When an interest group has a non-empty `priorityVector`, its priority is dynically calculted before applying `perBuyerGroupLimits`. To do this, the sparse dot product of interest group's `priorityVector` is multiplied by a `prioritySignals` vector. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entry in objects earlier in the list taking priority over entries later in the list: * The interest group's `prioritySignalsOverrides` field. * A browser-generated `prioritySignals` object, defined below. From 156b3d051b7ef9a98a81c5f3ed2ec0fd016a696c Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Mon, 25 Jul 2022 18:06:07 -0400 Subject: [PATCH 06/27] Update FLEDGE.md --- FLEDGE.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 806c2f901..07f9457f5 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -132,7 +132,7 @@ The `userBiddingSignals` is for storage of additional metadata that the owner ca The `biddingWasmHelperUrl` field is optional, and lets the bidder provide computationally-expensive subroutines in WebAssembly, rather than JavaScript, to be driven from the JavaScript function provided by `biddingLogicUrl`. If provided, it must point to a WebAssembly binary, delivered with an `application/wasm` mimetype. The corresponding `WebAssembly.Module` will be made available by the browser to the `generateBid` function. -The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically update the attributes of the interest group: any new values returned in this way overwrite the values previously stored (except that the `name` and `owner` cannot be changed). However, the browser will only allow daily updates when a sufficiently large number of people have the same `dailyUpdateUrl` , e.g. at least 100 browsers with the same update URL. This will not include any metadata, so data such as the interest group `name` should be included within the URL, so long as the URL exceeds the minimum count threshold. (Without this sort of limit, a single-person interest group could be used to observe that person's coarse-grained IP-Geo location over time.) +The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically update the attributes of the interest group: any new values returned in this way overwrite the values previously stored (except that the `name` and `owner` cannot be changed, and `perBrowserSignalsOverrides` will be merged with the previous value). However, the browser will only allow daily updates when a sufficiently large number of people have the same `dailyUpdateUrl` , e.g. at least 100 browsers with the same update URL. This will not include any metadata, so data such as the interest group `name` should be included within the URL, so long as the URL exceeds the minimum count threshold. (Without this sort of limit, a single-person interest group could be used to observe that person's coarse-grained IP-Geo location over time.) 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. @@ -409,7 +409,7 @@ The arguments to `generateBid()` are: * interestGroup: The interest group object, as saved during `joinAdInterestGroup()` and perhaps updated via the `dailyUpdateUrl`. - * `priority` and `prioritySignalsOverrides` are not included. The can be modified by generatedBid() calls, so could theoretically be used to create a cross-site profile of a user by adding data when an interest group participates in an auction, so are not included. + * `priority` and `prioritySignalsOverrides` are not included. They can be modified by generatedBid() calls, so could theoretically be used to create a cross-site profile of a user accessible to generateBid() methods, otherwise. * auctionSignals: As provided by the seller in the call to `runAdAuction()`. This is the opportunity for the seller to provide information about the page context (ad size, publisher ID, etc), the type of auction (first-price vs second-price), and so on. * perBuyerSignals: The value for _this specific buyer_ as taken from the auction config passed to `runAdAuction()`. This can include contextual signals about the page that come from the buyer's server, if the seller is an SSP which performs a real-time bidding call to buyer servers and pipes the response back, or if the publisher page contacts the buyer's server directly. If so, the buyer may wish to check a cryptographic signature of those signals inside `generateBid()` as protection against tampering. * trustedBiddingSignals: An object whose keys are the `trustedBiddingSignalsKeys` for the interest group, and whose values are those returned in the `trustedBiddingSignals` request. @@ -436,6 +436,8 @@ The output of `generateBid()` contains the following fields: * 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. * 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. + #### 3.3 Metadata with the Ad Bid @@ -474,7 +476,7 @@ If the resulting dot-product is negative, the interest group is immediately remo If `enableBiddingSignalsPrioritization` is `true`, then rather than applying `perBuyerGroupLimits` immediately after the the calculating the sparse dot product as desribed above (if `priorityVector` is non-null), then instead, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is a again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that it may have a non-zero `browserSignals.firstDotProductPriority` value. If this dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. -The advantage of having not using `enableBiddingSignalsPrioritization` is that interest groups can be filtered out before bidding signals are fetched. In auctions with large numbers of buyers auctions, some buyers may also be able to filter themselves out entirely, which could significantly improve performance. +The advantage of having not using `enableBiddingSignalsPrioritization` is that interest groups can be filtered out before bidding signals are fetched, reducing network usage and server load. In auctions with large numbers of buyers auctions, some buyers may also be able to filter themselves out entirely, which could significantly improve performance. ### 4. Browsers Render the Winning Ad From 8ef5cf406dd219521ac13a1abb75d1189e208b67 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Mon, 25 Jul 2022 18:20:46 -0400 Subject: [PATCH 07/27] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 07f9457f5..d759b1aba 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -132,7 +132,7 @@ The `userBiddingSignals` is for storage of additional metadata that the owner ca The `biddingWasmHelperUrl` field is optional, and lets the bidder provide computationally-expensive subroutines in WebAssembly, rather than JavaScript, to be driven from the JavaScript function provided by `biddingLogicUrl`. If provided, it must point to a WebAssembly binary, delivered with an `application/wasm` mimetype. The corresponding `WebAssembly.Module` will be made available by the browser to the `generateBid` function. -The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically update the attributes of the interest group: any new values returned in this way overwrite the values previously stored (except that the `name` and `owner` cannot be changed, and `perBrowserSignalsOverrides` will be merged with the previous value). However, the browser will only allow daily updates when a sufficiently large number of people have the same `dailyUpdateUrl` , e.g. at least 100 browsers with the same update URL. This will not include any metadata, so data such as the interest group `name` should be included within the URL, so long as the URL exceeds the minimum count threshold. (Without this sort of limit, a single-person interest group could be used to observe that person's coarse-grained IP-Geo location over time.) +The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically update the attributes of the interest group: any new values returned in this way overwrite the values previously stored (except that the `name` and `owner` cannot be changed, and `perBrowserSignalsOverrides` will be merged with the previous value, with "null" meaning a value should be removed from the interest group's old value). However, the browser will only allow daily updates when a sufficiently large number of people have the same `dailyUpdateUrl` , e.g. at least 100 browsers with the same update URL. This will not include any metadata, so data such as the interest group `name` should be included within the URL, so long as the URL exceeds the minimum count threshold. (Without this sort of limit, a single-person interest group could be used to observe that person's coarse-grained IP-Geo location over time.) 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. From 31e29fd0751fbc52a5013b33e2a32ba68e5e897f Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Mon, 25 Jul 2022 18:22:04 -0400 Subject: [PATCH 08/27] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index d759b1aba..02c972d56 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -132,7 +132,7 @@ The `userBiddingSignals` is for storage of additional metadata that the owner ca The `biddingWasmHelperUrl` field is optional, and lets the bidder provide computationally-expensive subroutines in WebAssembly, rather than JavaScript, to be driven from the JavaScript function provided by `biddingLogicUrl`. If provided, it must point to a WebAssembly binary, delivered with an `application/wasm` mimetype. The corresponding `WebAssembly.Module` will be made available by the browser to the `generateBid` function. -The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically update the attributes of the interest group: any new values returned in this way overwrite the values previously stored (except that the `name` and `owner` cannot be changed, and `perBrowserSignalsOverrides` will be merged with the previous value, with "null" meaning a value should be removed from the interest group's old value). However, the browser will only allow daily updates when a sufficiently large number of people have the same `dailyUpdateUrl` , e.g. at least 100 browsers with the same update URL. This will not include any metadata, so data such as the interest group `name` should be included within the URL, so long as the URL exceeds the minimum count threshold. (Without this sort of limit, a single-person interest group could be used to observe that person's coarse-grained IP-Geo location over time.) +The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically update the attributes of the interest group: any new values returned in this way overwrite the values previously stored (except that the `name` and `owner` cannot be changed, and `perBrowserSignalsOverrides` will be merged with the previous value, with `null` meaning a value should be removed from the interest group's old dictionary). However, the browser will only allow daily updates when a sufficiently large number of people have the same `dailyUpdateUrl` , e.g. at least 100 browsers with the same update URL. This will not include any metadata, so data such as the interest group `name` should be included within the URL, so long as the URL exceeds the minimum count threshold. (Without this sort of limit, a single-person interest group could be used to observe that person's coarse-grained IP-Geo location over time.) 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. From 8aaa6d56bc37c822294145323d960683c0cf8cda Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Wed, 27 Jul 2022 12:58:38 -0400 Subject: [PATCH 09/27] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 02c972d56..0ff1ad0c6 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -457,7 +457,7 @@ The output of `generateBid()` can use the on-device ad composition flow through #### 3.5 Prioritizing Interest Groups -When an interest group has a non-empty `priorityVector`, its priority is dynically calculted before applying `perBuyerGroupLimits`. To do this, the sparse dot product of interest group's `priorityVector` is multiplied by a `prioritySignals` vector. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entry in objects earlier in the list taking priority over entries later in the list: +When an interest group has a non-empty `priorityVector`, its priority is dynically calculted before applying `perBuyerGroupLimits`. To do this, the sparse dot product of interest group's `priorityVector` is multiplied by a `prioritySignals` vector. The `sparse dot product` of two vectors `V` and `W` is the sum of the products `V[key] * W[key]` for each key in both `V` and `W`. For example, the sparse dot product of `{'x':3, 'y':7, 'z':12}` with `{'x':-2, 'y':1.7, 'teapot':418}` is `3*(-2) + 7*1.7 = 5.9`. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entry in objects earlier in the list taking priority over entries later in the list: * The interest group's `prioritySignalsOverrides` field. * A browser-generated `prioritySignals` object, defined below. From 75b398eb5e1b36327c2473be17cbaeed86b859b2 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Wed, 27 Jul 2022 13:02:41 -0400 Subject: [PATCH 10/27] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 0ff1ad0c6..f0d6b29ff 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -457,7 +457,7 @@ The output of `generateBid()` can use the on-device ad composition flow through #### 3.5 Prioritizing Interest Groups -When an interest group has a non-empty `priorityVector`, its priority is dynically calculted before applying `perBuyerGroupLimits`. To do this, the sparse dot product of interest group's `priorityVector` is multiplied by a `prioritySignals` vector. The `sparse dot product` of two vectors `V` and `W` is the sum of the products `V[key] * W[key]` for each key in both `V` and `W`. For example, the sparse dot product of `{'x':3, 'y':7, 'z':12}` with `{'x':-2, 'y':1.7, 'teapot':418}` is `3*(-2) + 7*1.7 = 5.9`. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entry in objects earlier in the list taking priority over entries later in the list: +When an interest group has a non-empty `priorityVector`, its priority is dynically calculted before applying `perBuyerGroupLimits`. To do this, the sparse dot product of interest group's `priorityVector` is multiplied by a `prioritySignals` vector. The __sparse dot product__ of two vectors `V` and `W` is the sum of the products `V[key] * W[key]` for each key in both `V` and `W`. For example, the sparse dot product of `{'x':3, 'y':7, 'z':12}` with `{'x':-2, 'y':1.7, 'teapot':418}` is `3*(-2) + 7*1.7 = 5.9`. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entry in objects earlier in the list taking priority over entries later in the list: * The interest group's `prioritySignalsOverrides` field. * A browser-generated `prioritySignals` object, defined below. From 10560a13334740d4ae5399c3d3fffa65441be124 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 28 Jul 2022 16:29:05 -0400 Subject: [PATCH 11/27] Update FLEDGE.md --- FLEDGE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index f0d6b29ff..e5c49021a 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -457,7 +457,7 @@ The output of `generateBid()` can use the on-device ad composition flow through #### 3.5 Prioritizing Interest Groups -When an interest group has a non-empty `priorityVector`, its priority is dynically calculted before applying `perBuyerGroupLimits`. To do this, the sparse dot product of interest group's `priorityVector` is multiplied by a `prioritySignals` vector. The __sparse dot product__ of two vectors `V` and `W` is the sum of the products `V[key] * W[key]` for each key in both `V` and `W`. For example, the sparse dot product of `{'x':3, 'y':7, 'z':12}` with `{'x':-2, 'y':1.7, 'teapot':418}` is `3*(-2) + 7*1.7 = 5.9`. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entry in objects earlier in the list taking priority over entries later in the list: +When an interest group has a non-empty `priorityVector`, its priority is dynamically calculted before applying `perBuyerGroupLimits`. To do this, the sparse dot product of interest group's `priorityVector` is multiplied by a `prioritySignals` vector. The __sparse dot product__ of two vectors `V` and `W` is the sum of the products `V[key] * W[key]` for each key in both `V` and `W`. For example, the sparse dot product of `{'x':3, 'y':7, 'z':12}` with `{'x':-2, 'y':1.7, 'teapot':418}` is `3*(-2) + 7*1.7 = 5.9`. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entry in objects earlier in the list taking priority over entries later in the list: * The interest group's `prioritySignalsOverrides` field. * A browser-generated `prioritySignals` object, defined below. @@ -472,7 +472,7 @@ The browser-generated `prioritySignals` object contains the following values: * `browserSignals.basePriority`: The priority field in the interest group, which may have been modified by a setPriority() call. * `browserSignals.firstDotProductPriority`: The priority from multiplying the interest group's `priorityVector` by `prioritySignals`. Only non-zero when using a `proirityVector` from a trusted bidding signals fetch, and the interest group also has a `prioritySignals` field. See below for more details. -If the resulting dot-product is negative, the interest group is immediately removed from an auction (Note that if there's no `priorityVector`, interest groups with negative values currently are not filtered from auctions). After calculting new priorities, as needed, and filtering out interest groups with negative calculated priorities, the `perBuyerGroupLimits` value is applied to all interest groups of a given order, unless the interest group's `enableBiddingSignalsPrioritization` field is present and true. +If the resulting dot-product is negative, the interest group is immediately removed from an auction (Note that if there's no `priorityVector`, interest groups with negative values currently are not filtered from auctions). After calculating new priorities as needed, and filtering out interest groups with negative calculated priorities, the `perBuyerGroupLimits` value is applied to all interest groups of a given owner, unless the interest group's `enableBiddingSignalsPrioritization` field is present and true. If `enableBiddingSignalsPrioritization` is `true`, then rather than applying `perBuyerGroupLimits` immediately after the the calculating the sparse dot product as desribed above (if `priorityVector` is non-null), then instead, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is a again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that it may have a non-zero `browserSignals.firstDotProductPriority` value. If this dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. From 06bcbd35bd228f4519bf849d1d5c10cf7183653a Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 4 Aug 2022 15:03:43 -0400 Subject: [PATCH 12/27] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index e5c49021a..05f8f58ae 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -468,7 +468,7 @@ Additionally, keys starting with "browserSignals." are reserved, and may only ap The browser-generated `prioritySignals` object contains the following values: * `browserSignals.one`: This is always 1. It's useful for adding a constant to the dot product. -* `browserSignals.age`: How long ago the user was added to the interest group, in milliseconds. This is the most recent time the use was added to the injterest group, so re-joining an interest group resets the value. This value is always non-negative. +* `browserSignals.age`: How long ago the user was added to the interest group, in milliseconds. This is the most recent time the user was added to the interest group, so re-joining an interest group resets the value. This value is always non-negative. * `browserSignals.basePriority`: The priority field in the interest group, which may have been modified by a setPriority() call. * `browserSignals.firstDotProductPriority`: The priority from multiplying the interest group's `priorityVector` by `prioritySignals`. Only non-zero when using a `proirityVector` from a trusted bidding signals fetch, and the interest group also has a `prioritySignals` field. See below for more details. From 146fcddc0b2782de0295681419f488a9d76ddf2e Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 11 Aug 2022 11:40:21 -0400 Subject: [PATCH 13/27] Update FLEDGE.md --- FLEDGE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 05f8f58ae..9e870e884 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -351,7 +351,7 @@ and the server must include the HTTP response header `X-fledge-bidding-signals-f The value of each key that an interest group has in its `trustedBiddingSignalsKeys` list will be passed from the `keys` dictionary to the interest group's generateBid() function as the `trustedBiddingSignals` parameter. Values missing from the JSON object will be set to null. If the JSON download fails, or there are no `trustedBiddingSignalsKeys` or `trustedBiddingSignalsUrl` in the interest group, then the `trustedBiddingSignals` argument to generateBid() will be null. -The `perInterestGroupData` dictionary contains optional data for interest groups whose names were included in the request URL. The `priorityVector` will be used as the priority for an interest group, if that interest group has `enableBiddingSignalsPrioritization` set to `true` in its definition. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. +The `perInterestGroupData` dictionary contains optional data for interest groups whose names were included in the request URL. The `priorityVector` will be used to calculate the final priority for an interest group, if that interest group has `enableBiddingSignalsPrioritization` set to `true` in its definition. Otherwise, it's only used to filter out interest groups, if the result of multipling it by the `prioritySignals` is nevative. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. Similarly, sellers may want to fetch information about a specific creative, e.g. the results of some out-of-band ad scanning system. This works in much the same way, with the base URL coming from the `trustedScoringSignalsUrl` property of the seller's auction configuration object. However, it has two sets of keys: "renderUrls=url1,url2,..." and "adComponentRenderUrls=url1,url2,..." for the main and adComponent renderUrls bids offered in the auction. It is up to the client how and whether to aggregate the fetches with the URLs of multiple bidders. The response to this request should be in the form: @@ -476,6 +476,8 @@ If the resulting dot-product is negative, the interest group is immediately remo If `enableBiddingSignalsPrioritization` is `true`, then rather than applying `perBuyerGroupLimits` immediately after the the calculating the sparse dot product as desribed above (if `priorityVector` is non-null), then instead, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is a again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that it may have a non-zero `browserSignals.firstDotProductPriority` value. If this dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. +if `enableBiddingSignalsPrioritization` is false, then the `priorityVector` from the trusted bidding singals will still be multiplied by the `prioritySignals` as above, but it will only be used to skip the interest group if the result is less than 0. + The advantage of having not using `enableBiddingSignalsPrioritization` is that interest groups can be filtered out before bidding signals are fetched, reducing network usage and server load. In auctions with large numbers of buyers auctions, some buyers may also be able to filter themselves out entirely, which could significantly improve performance. From 800597b5c1458e3bb46ee78990b4c16a1075804e Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Wed, 17 Aug 2022 11:27:30 -0400 Subject: [PATCH 14/27] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 9e870e884..84d64196c 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -126,7 +126,7 @@ The browser will remain in an interest group for only a limited amount of time. The `priority` is used to select which interest groups participate in an auction when the number of interest groups are limited by the `perBuyerGroupLimits` attribute of the auction config. If not specified, a `priority` of `0.0` is assigned. There is no special meaning to these values. These values are only used to select interest groups to participate in an auction such that if there is an interest group participating in the auction with priority `x`, all interest groups with the same owner having a priority `y` where `y > x` should also participate (i.e. `generateBid` will be called). In the case where some but not all interest groups with equal priority can participate in an auction due to `perBuyerGroupLimits`, the participating interest groups will be uniformly randomly chosen from the set of interest groups with that priority. -`priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization` are optional values used to dymnically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while enableBiddingSignalsPrioritization is a bool that defaults to `false`. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for a description of how these fields are used. +`priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization` are optional values used to dynamically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while enableBiddingSignalsPrioritization is a bool that defaults to `false`. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for a description of how these fields are used. The `userBiddingSignals` is for storage of additional metadata that the owner can use during on-device bidding, and the `trustedBiddingSignals` attributes provide another mechanism for making real-time data available for use at bidding time. From 2d8b8bbcf594753567a30175caa83b06f1ff2677 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Tue, 23 Aug 2022 16:17:44 -0400 Subject: [PATCH 15/27] Update FLEDGE.md --- FLEDGE.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 84d64196c..1cbb713e0 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -468,9 +468,12 @@ Additionally, keys starting with "browserSignals." are reserved, and may only ap The browser-generated `prioritySignals` object contains the following values: * `browserSignals.one`: This is always 1. It's useful for adding a constant to the dot product. -* `browserSignals.age`: How long ago the user was added to the interest group, in milliseconds. This is the most recent time the user was added to the interest group, so re-joining an interest group resets the value. This value is always non-negative. * `browserSignals.basePriority`: The priority field in the interest group, which may have been modified by a setPriority() call. * `browserSignals.firstDotProductPriority`: The priority from multiplying the interest group's `priorityVector` by `prioritySignals`. Only non-zero when using a `proirityVector` from a trusted bidding signals fetch, and the interest group also has a `prioritySignals` field. See below for more details. +* `browserSignals.ageInMinutes`: How long since the interest group was most recently joined, in minutes. Guaranteed to be between 0 and 43200 (the number of minutes in 30 days, the maximum lifetime of an interest group), inclusive. +* `browserSignals.ageInMinutesMax60`: Same as `browserSignals.ageInMinutes`, but with a maximum value of 60, which is returned if the group is more than an hour old. +* `browserSignals.ageInHoursMax24`: The interset group's age in hours, with a maximum value of 24. +* `browserSignals.ageInDaysMax30`: The interset group's age in days, with a maximum value of 30. If the resulting dot-product is negative, the interest group is immediately removed from an auction (Note that if there's no `priorityVector`, interest groups with negative values currently are not filtered from auctions). After calculating new priorities as needed, and filtering out interest groups with negative calculated priorities, the `perBuyerGroupLimits` value is applied to all interest groups of a given owner, unless the interest group's `enableBiddingSignalsPrioritization` field is present and true. From 6369085cb3890d361dd7f7a12a90d5dff8457c4b Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Tue, 23 Aug 2022 16:22:28 -0400 Subject: [PATCH 16/27] Update FLEDGE.md --- FLEDGE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 1cbb713e0..b78022af9 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -470,10 +470,10 @@ The browser-generated `prioritySignals` object contains the following values: * `browserSignals.one`: This is always 1. It's useful for adding a constant to the dot product. * `browserSignals.basePriority`: The priority field in the interest group, which may have been modified by a setPriority() call. * `browserSignals.firstDotProductPriority`: The priority from multiplying the interest group's `priorityVector` by `prioritySignals`. Only non-zero when using a `proirityVector` from a trusted bidding signals fetch, and the interest group also has a `prioritySignals` field. See below for more details. -* `browserSignals.ageInMinutes`: How long since the interest group was most recently joined, in minutes. Guaranteed to be between 0 and 43200 (the number of minutes in 30 days, the maximum lifetime of an interest group), inclusive. +* `browserSignals.ageInMinutes`: How long since the interest group was most recently joined, in minutes, as an integer. Guaranteed to be between 0 and 43200 (the number of minutes in 30 days, the maximum lifetime of an interest group), inclusive. * `browserSignals.ageInMinutesMax60`: Same as `browserSignals.ageInMinutes`, but with a maximum value of 60, which is returned if the group is more than an hour old. -* `browserSignals.ageInHoursMax24`: The interset group's age in hours, with a maximum value of 24. -* `browserSignals.ageInDaysMax30`: The interset group's age in days, with a maximum value of 30. +* `browserSignals.ageInHoursMax24`: The interest group's age in hours, as an integer, with a maximum value of 24. Always non-negative. +* `browserSignals.ageInDaysMax30`: The interest group's age in days, as an integer, with a maximum value of 30. Always non-negative. If the resulting dot-product is negative, the interest group is immediately removed from an auction (Note that if there's no `priorityVector`, interest groups with negative values currently are not filtered from auctions). After calculating new priorities as needed, and filtering out interest groups with negative calculated priorities, the `perBuyerGroupLimits` value is applied to all interest groups of a given owner, unless the interest group's `enableBiddingSignalsPrioritization` field is present and true. From 3f8b88da95f0942593c8fb244a5af156da9b0125 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Wed, 7 Sep 2022 15:22:00 -0400 Subject: [PATCH 17/27] Update FLEDGE.md --- FLEDGE.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index b78022af9..d9faefebe 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -479,9 +479,7 @@ If the resulting dot-product is negative, the interest group is immediately remo If `enableBiddingSignalsPrioritization` is `true`, then rather than applying `perBuyerGroupLimits` immediately after the the calculating the sparse dot product as desribed above (if `priorityVector` is non-null), then instead, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is a again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that it may have a non-zero `browserSignals.firstDotProductPriority` value. If this dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. -if `enableBiddingSignalsPrioritization` is false, then the `priorityVector` from the trusted bidding singals will still be multiplied by the `prioritySignals` as above, but it will only be used to skip the interest group if the result is less than 0. - -The advantage of having not using `enableBiddingSignalsPrioritization` is that interest groups can be filtered out before bidding signals are fetched, reducing network usage and server load. In auctions with large numbers of buyers auctions, some buyers may also be able to filter themselves out entirely, which could significantly improve performance. +if `enableBiddingSignalsPrioritization` is false, then the `priorityVector` from the trusted bidding singals will still be multiplied by the `prioritySignals` as above, but it will only be used to skip the interest group if the result is less than 0. This parameter exists to improve performance - when it's false for all interest groups for a particular bidder in an auction, that bidder's interest groups can be filtered out before any bidding signals are fetched, reducing network usage and server load. ### 4. Browsers Render the Winning Ad From b11d27dc14d37db3dacb3c7c965fbbc19d971127 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Wed, 7 Sep 2022 15:27:12 -0400 Subject: [PATCH 18/27] Update FLEDGE.md --- FLEDGE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index d9faefebe..42513aa18 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -351,7 +351,7 @@ and the server must include the HTTP response header `X-fledge-bidding-signals-f The value of each key that an interest group has in its `trustedBiddingSignalsKeys` list will be passed from the `keys` dictionary to the interest group's generateBid() function as the `trustedBiddingSignals` parameter. Values missing from the JSON object will be set to null. If the JSON download fails, or there are no `trustedBiddingSignalsKeys` or `trustedBiddingSignalsUrl` in the interest group, then the `trustedBiddingSignals` argument to generateBid() will be null. -The `perInterestGroupData` dictionary contains optional data for interest groups whose names were included in the request URL. The `priorityVector` will be used to calculate the final priority for an interest group, if that interest group has `enableBiddingSignalsPrioritization` set to `true` in its definition. Otherwise, it's only used to filter out interest groups, if the result of multipling it by the `prioritySignals` is nevative. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. +The `perInterestGroupData` dictionary contains optional data for interest groups whose names were included in the request URL. The `priorityVector` will be used to calculate the final priority for an interest group, if that interest group has `enableBiddingSignalsPrioritization` set to true in its definition. Otherwise, it's only used to filter out interest groups, if the result of multipling it by the `prioritySignals` is nevative. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. Similarly, sellers may want to fetch information about a specific creative, e.g. the results of some out-of-band ad scanning system. This works in much the same way, with the base URL coming from the `trustedScoringSignalsUrl` property of the seller's auction configuration object. However, it has two sets of keys: "renderUrls=url1,url2,..." and "adComponentRenderUrls=url1,url2,..." for the main and adComponent renderUrls bids offered in the auction. It is up to the client how and whether to aggregate the fetches with the URLs of multiple bidders. The response to this request should be in the form: @@ -477,7 +477,7 @@ The browser-generated `prioritySignals` object contains the following values: If the resulting dot-product is negative, the interest group is immediately removed from an auction (Note that if there's no `priorityVector`, interest groups with negative values currently are not filtered from auctions). After calculating new priorities as needed, and filtering out interest groups with negative calculated priorities, the `perBuyerGroupLimits` value is applied to all interest groups of a given owner, unless the interest group's `enableBiddingSignalsPrioritization` field is present and true. -If `enableBiddingSignalsPrioritization` is `true`, then rather than applying `perBuyerGroupLimits` immediately after the the calculating the sparse dot product as desribed above (if `priorityVector` is non-null), then instead, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is a again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that it may have a non-zero `browserSignals.firstDotProductPriority` value. If this dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. +If `enableBiddingSignalsPrioritization` is true, then rather than applying `perBuyerGroupLimits` immediately after the the calculating the sparse dot product as desribed above, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is a again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that that there's an addition `browserSignals.firstDotProductPriority` value, which is the result of multiplying the interest group's `priorityVector`, if present, with the `prioritySignals` of the auction. If this new dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. if `enableBiddingSignalsPrioritization` is false, then the `priorityVector` from the trusted bidding singals will still be multiplied by the `prioritySignals` as above, but it will only be used to skip the interest group if the result is less than 0. This parameter exists to improve performance - when it's false for all interest groups for a particular bidder in an auction, that bidder's interest groups can be filtered out before any bidding signals are fetched, reducing network usage and server load. From ac326f1f75f66a34e9dc8628db19bdecaccd608a Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 15 Sep 2022 20:03:45 -0400 Subject: [PATCH 19/27] 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 42513aa18..965d5cd7a 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -126,7 +126,7 @@ The browser will remain in an interest group for only a limited amount of time. The `priority` is used to select which interest groups participate in an auction when the number of interest groups are limited by the `perBuyerGroupLimits` attribute of the auction config. If not specified, a `priority` of `0.0` is assigned. There is no special meaning to these values. These values are only used to select interest groups to participate in an auction such that if there is an interest group participating in the auction with priority `x`, all interest groups with the same owner having a priority `y` where `y > x` should also participate (i.e. `generateBid` will be called). In the case where some but not all interest groups with equal priority can participate in an auction due to `perBuyerGroupLimits`, the participating interest groups will be uniformly randomly chosen from the set of interest groups with that priority. -`priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization` are optional values used to dynamically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while enableBiddingSignalsPrioritization is a bool that defaults to `false`. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for a description of how these fields are used. +`priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization` are optional values used to dynamically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while `enableBiddingSignalsPrioritization` is a bool that defaults to `false`. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for a description of how these fields are used. The `userBiddingSignals` is for storage of additional metadata that the owner can use during on-device bidding, and the `trustedBiddingSignals` attributes provide another mechanism for making real-time data available for use at bidding time. From 11436339514d48a902a8d21a9fedc5eabd332070 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 15 Sep 2022 20:04:29 -0400 Subject: [PATCH 20/27] 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 965d5cd7a..1ef603997 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -224,7 +224,7 @@ Optionally, `sellerTimeout` can be specified to restrict the runtime (in millise Optionally, `perBuyerGroupLimits` can be specified to limit the number of of interest groups from a particular buyer that participate in the auction. A key of `'*'` in `perBuyerGroupLimits` is used to set a limit for unspecified buyers. For each buyer, interest groups will be selected to participate in the auction in order of decreasing `priority` (larger priorities are selected first) up to the specfied limit. The selection of interest groups occurs independently for each buyer, so the priorities do not need to be comparable between buyers and could have a buyer-specific meaning. The value of the limits provided should be able to be represented by a 16 bit unsigned integer. -Optionally, `perBuyerPrioritySignals` is an object mapping string keys to Javascript numbers that can be used to dynamically compute interest group priorities before perBuyerGroupLimits are applied. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. +Optionally, `perBuyerPrioritySignals` is an object mapping string keys to Javascript numbers that can be used to dynamically compute interest group priorities before `perBuyerGroupLimits` are applied. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. All fields that accept arbitrary metadata objects (`auctionSignals`, `sellerSignals`, and keys of `perBuyerSignals`) must be JSON-serializable. From 0ae2dc7bfe2e929110eb9222cfc5d2dd42fb26a4 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 15 Sep 2022 20:04:45 -0400 Subject: [PATCH 21/27] 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 1ef603997..aad89fa65 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -326,7 +326,7 @@ Buyers may want to make on-device decisions that take into account real-time dat https://www.kv-server.example/getvalues?hostname=publisher.com&keys=key1,key2&interestGroups=name1,name2 -The base URL `https://www.kv-server.example/getvalues` comes from the interest group's `trustedBiddingSignalsUrl`, the hostname of the top-level webpage where the ad will appear `publisher.com` is provided by the browser, `keys` is a list of `trustedBiddingSignalsKeys` strings, and interestGroupNames is a list of the names of interest groups data is being fetched for. The requests may be coalesced (for efficiency) across any number of interest groups that share a `trustedBiddingSignalsUrl` (which means they also share an owner). +The base URL `https://www.kv-server.example/getvalues` comes from the interest group's `trustedBiddingSignalsUrl`, the hostname of the top-level webpage where the ad will appear `publisher.com` is provided by the browser, `keys` is a list of `trustedBiddingSignalsKeys` strings, and `interestGroupNames` is a list of the names of the interest groups that data is being fetched for. The requests may be coalesced (for efficiency) across any number of interest groups that share a `trustedBiddingSignalsUrl` (which means they also share an owner). The response from the server should be a JSON object of the form: From de7578e013f022978286974556c60152457499e8 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 29 Sep 2022 13:11:15 -0400 Subject: [PATCH 22/27] Update FLEDGE.md --- FLEDGE.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index aad89fa65..27554f100 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -132,7 +132,7 @@ The `userBiddingSignals` is for storage of additional metadata that the owner ca The `biddingWasmHelperUrl` field is optional, and lets the bidder provide computationally-expensive subroutines in WebAssembly, rather than JavaScript, to be driven from the JavaScript function provided by `biddingLogicUrl`. If provided, it must point to a WebAssembly binary, delivered with an `application/wasm` mimetype. The corresponding `WebAssembly.Module` will be made available by the browser to the `generateBid` function. -The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically update the attributes of the interest group: any new values returned in this way overwrite the values previously stored (except that the `name` and `owner` cannot be changed, and `perBrowserSignalsOverrides` will be merged with the previous value, with `null` meaning a value should be removed from the interest group's old dictionary). However, the browser will only allow daily updates when a sufficiently large number of people have the same `dailyUpdateUrl` , e.g. at least 100 browsers with the same update URL. This will not include any metadata, so data such as the interest group `name` should be included within the URL, so long as the URL exceeds the minimum count threshold. (Without this sort of limit, a single-person interest group could be used to observe that person's coarse-grained IP-Geo location over time.) +The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically update the attributes of the interest group: any new values returned in this way overwrite the values previously stored (except that the `name` and `owner` cannot be changed, and `prioritySignalsOverrides` will be merged with the previous value, with `null` meaning a value should be removed from the interest group's old dictionary). However, the browser will only allow daily updates when a sufficiently large number of people have the same `dailyUpdateUrl` , e.g. at least 100 browsers with the same update URL. This will not include any metadata, so data such as the interest group `name` should be included within the URL, so long as the URL exceeds the minimum count threshold. (Without this sort of limit, a single-person interest group could be used to observe that person's coarse-grained IP-Geo location over time.) 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. @@ -351,7 +351,7 @@ and the server must include the HTTP response header `X-fledge-bidding-signals-f The value of each key that an interest group has in its `trustedBiddingSignalsKeys` list will be passed from the `keys` dictionary to the interest group's generateBid() function as the `trustedBiddingSignals` parameter. Values missing from the JSON object will be set to null. If the JSON download fails, or there are no `trustedBiddingSignalsKeys` or `trustedBiddingSignalsUrl` in the interest group, then the `trustedBiddingSignals` argument to generateBid() will be null. -The `perInterestGroupData` dictionary contains optional data for interest groups whose names were included in the request URL. The `priorityVector` will be used to calculate the final priority for an interest group, if that interest group has `enableBiddingSignalsPrioritization` set to true in its definition. Otherwise, it's only used to filter out interest groups, if the result of multipling it by the `prioritySignals` is nevative. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. +The `perInterestGroupData` dictionary contains optional data for interest groups whose names were included in the request URL. The `priorityVector` will be used to calculate the final priority for an interest group, if that interest group has `enableBiddingSignalsPrioritization` set to true in its definition. Otherwise, it's only used to filter out interest groups, if the result of multipling it by the `prioritySignals` is negative. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. Similarly, sellers may want to fetch information about a specific creative, e.g. the results of some out-of-band ad scanning system. This works in much the same way, with the base URL coming from the `trustedScoringSignalsUrl` property of the seller's auction configuration object. However, it has two sets of keys: "renderUrls=url1,url2,..." and "adComponentRenderUrls=url1,url2,..." for the main and adComponent renderUrls bids offered in the auction. It is up to the client how and whether to aggregate the fetches with the URLs of multiple bidders. The response to this request should be in the form: @@ -475,9 +475,9 @@ The browser-generated `prioritySignals` object contains the following values: * `browserSignals.ageInHoursMax24`: The interest group's age in hours, as an integer, with a maximum value of 24. Always non-negative. * `browserSignals.ageInDaysMax30`: The interest group's age in days, as an integer, with a maximum value of 30. Always non-negative. -If the resulting dot-product is negative, the interest group is immediately removed from an auction (Note that if there's no `priorityVector`, interest groups with negative values currently are not filtered from auctions). After calculating new priorities as needed, and filtering out interest groups with negative calculated priorities, the `perBuyerGroupLimits` value is applied to all interest groups of a given owner, unless the interest group's `enableBiddingSignalsPrioritization` field is present and true. +If the resulting dot-product is negative, the interest group is immediately removed from an auction (note that if there's no `priorityVector`, interest groups with negative values currently are not filtered from auctions). After calculating new priorities as needed, and filtering out interest groups with negative calculated priorities, the `perBuyerGroupLimits` value is applied to all interest groups of a given owner, unless the interest group's `enableBiddingSignalsPrioritization` field is present and true. -If `enableBiddingSignalsPrioritization` is true, then rather than applying `perBuyerGroupLimits` immediately after the the calculating the sparse dot product as desribed above, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is a again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that that there's an addition `browserSignals.firstDotProductPriority` value, which is the result of multiplying the interest group's `priorityVector`, if present, with the `prioritySignals` of the auction. If this new dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. +If `enableBiddingSignalsPrioritization` is true, then rather than applying `perBuyerGroupLimits` immediately after the calculating the sparse dot product as desribed above, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that that there's an addition `browserSignals.firstDotProductPriority` value, which is the result of multiplying the interest group's `priorityVector`, if present, with the `prioritySignals` of the auction. If this new dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. if `enableBiddingSignalsPrioritization` is false, then the `priorityVector` from the trusted bidding singals will still be multiplied by the `prioritySignals` as above, but it will only be used to skip the interest group if the result is less than 0. This parameter exists to improve performance - when it's false for all interest groups for a particular bidder in an auction, that bidder's interest groups can be filtered out before any bidding signals are fetched, reducing network usage and server load. From 7d3f9dfcfaa116b5582f44994aa8fa537f975dce Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Wed, 5 Oct 2022 15:20:05 -0400 Subject: [PATCH 23/27] Update FLEDGE.md --- FLEDGE.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 27554f100..5c1b2e003 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -24,7 +24,7 @@ We plan to hold regular meetings under the auspices of the WICG to go through th - [3.2 On-Device Bidding](#32-on-device-bidding) - [3.3 Metadata with the Ad Bid](#33-metadata-with-the-ad-bid) - [3.4 Ads Composed of Multiple Pieces](#34-ads-composed-of-multiple-pieces) - - [3.5 Prioritizing Interest Groups](#35-prioritizing-interest-groups) + - [3.5 Filtering and Prioritizing Interest Groups](#35-filtering-and-prioritizing-interest-groups) - [4. Browsers Render the Winning Ad](#4-browsers-render-the-winning-ad) - [5. Event-Level Reporting (for now)](#5-event-level-reporting-for-now) - [5.1 Seller Reporting on Render](#51-seller-reporting-on-render) @@ -99,7 +99,7 @@ const myGroup = { 'signal2': 0, ... } - `enableBiddingSignalsPrioritization` : [true | false], + `enableBiddingSignalsPrioritization` : true, 'biddingLogicUrl': ..., 'biddingWasmHelperUrl': ..., 'dailyUpdateUrl': ..., @@ -126,7 +126,7 @@ The browser will remain in an interest group for only a limited amount of time. The `priority` is used to select which interest groups participate in an auction when the number of interest groups are limited by the `perBuyerGroupLimits` attribute of the auction config. If not specified, a `priority` of `0.0` is assigned. There is no special meaning to these values. These values are only used to select interest groups to participate in an auction such that if there is an interest group participating in the auction with priority `x`, all interest groups with the same owner having a priority `y` where `y > x` should also participate (i.e. `generateBid` will be called). In the case where some but not all interest groups with equal priority can participate in an auction due to `perBuyerGroupLimits`, the participating interest groups will be uniformly randomly chosen from the set of interest groups with that priority. -`priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization` are optional values used to dynamically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while `enableBiddingSignalsPrioritization` is a bool that defaults to `false`. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for a description of how these fields are used. +`priorityVector`, `prioritySignalsOverrides`, and `enableBiddingSignalsPrioritization` are optional values used to dynamically calculate a priority used in place of `priority`. `priorityVector` and `prioritySignalsOverrides` are mappings of strings to Javscript numbers, while `enableBiddingSignalsPrioritization` is a bool that defaults to `false`. See [Filtering and Prioritizing Interest Groups](#35-filtering-and-prioritizing-interest-groups) for a description of how these fields are used. The `userBiddingSignals` is for storage of additional metadata that the owner can use during on-device bidding, and the `trustedBiddingSignals` attributes provide another mechanism for making real-time data available for use at bidding time. @@ -224,7 +224,7 @@ Optionally, `sellerTimeout` can be specified to restrict the runtime (in millise Optionally, `perBuyerGroupLimits` can be specified to limit the number of of interest groups from a particular buyer that participate in the auction. A key of `'*'` in `perBuyerGroupLimits` is used to set a limit for unspecified buyers. For each buyer, interest groups will be selected to participate in the auction in order of decreasing `priority` (larger priorities are selected first) up to the specfied limit. The selection of interest groups occurs independently for each buyer, so the priorities do not need to be comparable between buyers and could have a buyer-specific meaning. The value of the limits provided should be able to be represented by a 16 bit unsigned integer. -Optionally, `perBuyerPrioritySignals` is an object mapping string keys to Javascript numbers that can be used to dynamically compute interest group priorities before `perBuyerGroupLimits` are applied. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. +Optionally, `perBuyerPrioritySignals` is an object mapping string keys to Javascript numbers that can be used to dynamically compute interest group priorities before `perBuyerGroupLimits` are applied. See [Filtering and Prioritizing Interest Groups](#35-filtering-and-prioritizing-interest-groups) for more information. All fields that accept arbitrary metadata objects (`auctionSignals`, `sellerSignals`, and keys of `perBuyerSignals`) must be JSON-serializable. @@ -351,7 +351,7 @@ and the server must include the HTTP response header `X-fledge-bidding-signals-f The value of each key that an interest group has in its `trustedBiddingSignalsKeys` list will be passed from the `keys` dictionary to the interest group's generateBid() function as the `trustedBiddingSignals` parameter. Values missing from the JSON object will be set to null. If the JSON download fails, or there are no `trustedBiddingSignalsKeys` or `trustedBiddingSignalsUrl` in the interest group, then the `trustedBiddingSignals` argument to generateBid() will be null. -The `perInterestGroupData` dictionary contains optional data for interest groups whose names were included in the request URL. The `priorityVector` will be used to calculate the final priority for an interest group, if that interest group has `enableBiddingSignalsPrioritization` set to true in its definition. Otherwise, it's only used to filter out interest groups, if the result of multipling it by the `prioritySignals` is negative. See [Prioritizing Interest Groups](#35-prioritizing-interest-groups) for more information. +The `perInterestGroupData` dictionary contains optional data for interest groups whose names were included in the request URL. The `priorityVector` will be used to calculate the final priority for an interest group, if that interest group has `enableBiddingSignalsPrioritization` set to true in its definition. Otherwise, it's only used to filter out interest groups, if the result of multipling it by the `prioritySignals` is negative. See [Filtering and Prioritizing Interest Groups](#35-filtering-and-prioritizing-interest-groups) for more information. Similarly, sellers may want to fetch information about a specific creative, e.g. the results of some out-of-band ad scanning system. This works in much the same way, with the base URL coming from the `trustedScoringSignalsUrl` property of the seller's auction configuration object. However, it has two sets of keys: "renderUrls=url1,url2,..." and "adComponentRenderUrls=url1,url2,..." for the main and adComponent renderUrls bids offered in the auction. It is up to the client how and whether to aggregate the fetches with the URLs of multiple bidders. The response to this request should be in the form: @@ -455,7 +455,7 @@ The [Product-level TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/PR The output of `generateBid()` can use the on-device ad composition flow through an optional adComponents field, listing additional URLs made available to the fenced frame the container URL is loaded in. The component URLs may be retrieved by calling `navigator.adAuctionComponents(numComponents)`, where numComponents is at most 20. To prevent bidder worklets from using this as a sidechannel to leak additional data to the fenced frame, exactly numComponents obfuscated URLs will be returned by this method, regardless of how many adComponent URLs were actually in the bid, even if the bid contained no adComponents, and the Interest Group itself had no adComponents either. -#### 3.5 Prioritizing Interest Groups +#### 3.5 Filtering and Prioritizing Interest Groups When an interest group has a non-empty `priorityVector`, its priority is dynamically calculted before applying `perBuyerGroupLimits`. To do this, the sparse dot product of interest group's `priorityVector` is multiplied by a `prioritySignals` vector. The __sparse dot product__ of two vectors `V` and `W` is the sum of the products `V[key] * W[key]` for each key in both `V` and `W`. For example, the sparse dot product of `{'x':3, 'y':7, 'z':12}` with `{'x':-2, 'y':1.7, 'teapot':418}` is `3*(-2) + 7*1.7 = 5.9`. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entry in objects earlier in the list taking priority over entries later in the list: From 692ab18d159f0353b7907a1e64c142e6424c0d6d Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Wed, 5 Oct 2022 15:25:46 -0400 Subject: [PATCH 24/27] Apply suggestions from code review Co-authored-by: Paul Jensen --- FLEDGE.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 5c1b2e003..8ef2d7f02 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -409,7 +409,7 @@ The arguments to `generateBid()` are: * interestGroup: The interest group object, as saved during `joinAdInterestGroup()` and perhaps updated via the `dailyUpdateUrl`. - * `priority` and `prioritySignalsOverrides` are not included. They can be modified by generatedBid() calls, so could theoretically be used to create a cross-site profile of a user accessible to generateBid() methods, otherwise. + * `priority` and `prioritySignalsOverrides` are not included. They can be modified by `generatedBid()` calls, so could theoretically be used to create a cross-site profile of a user accessible to `generateBid()` methods, otherwise. * auctionSignals: As provided by the seller in the call to `runAdAuction()`. This is the opportunity for the seller to provide information about the page context (ad size, publisher ID, etc), the type of auction (first-price vs second-price), and so on. * perBuyerSignals: The value for _this specific buyer_ as taken from the auction config passed to `runAdAuction()`. This can include contextual signals about the page that come from the buyer's server, if the seller is an SSP which performs a real-time bidding call to buyer servers and pipes the response back, or if the publisher page contacts the buyer's server directly. If so, the buyer may wish to check a cryptographic signature of those signals inside `generateBid()` as protection against tampering. * trustedBiddingSignals: An object whose keys are the `trustedBiddingSignalsKeys` for the interest group, and whose values are those returned in the `trustedBiddingSignals` request. @@ -436,7 +436,7 @@ The output of `generateBid()` contains the following fields: * 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. * 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. +`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. #### 3.3 Metadata with the Ad Bid @@ -457,7 +457,7 @@ The output of `generateBid()` can use the on-device ad composition flow through #### 3.5 Filtering and Prioritizing Interest Groups -When an interest group has a non-empty `priorityVector`, its priority is dynamically calculted before applying `perBuyerGroupLimits`. To do this, the sparse dot product of interest group's `priorityVector` is multiplied by a `prioritySignals` vector. The __sparse dot product__ of two vectors `V` and `W` is the sum of the products `V[key] * W[key]` for each key in both `V` and `W`. For example, the sparse dot product of `{'x':3, 'y':7, 'z':12}` with `{'x':-2, 'y':1.7, 'teapot':418}` is `3*(-2) + 7*1.7 = 5.9`. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entry in objects earlier in the list taking priority over entries later in the list: +When an interest group has a non-empty `priorityVector`, its priority is dynamically calculated before applying `perBuyerGroupLimits`. To do this, the browser computes the sparse dot product of the interest group's `priorityVector` and a `prioritySignals` vector. The __sparse dot product__ of two vectors `V` and `W` is the sum of the products `V[key] * W[key]` for each key in both `V` and `W`. For example, the sparse dot product of `{'x':3, 'y':7, 'z':12}` with `{'x':-2, 'y':1.7, 'teapot':418}` is `3*(-2) + 7*1.7 = 5.9`. The `prioritySignals` vector is the result of merging the following objects, which all have strings as keys and numbers as values, with entries in objects earlier in the list taking priority over entries later in the list: * The interest group's `prioritySignalsOverrides` field. * A browser-generated `prioritySignals` object, defined below. @@ -468,18 +468,18 @@ Additionally, keys starting with "browserSignals." are reserved, and may only ap The browser-generated `prioritySignals` object contains the following values: * `browserSignals.one`: This is always 1. It's useful for adding a constant to the dot product. -* `browserSignals.basePriority`: The priority field in the interest group, which may have been modified by a setPriority() call. -* `browserSignals.firstDotProductPriority`: The priority from multiplying the interest group's `priorityVector` by `prioritySignals`. Only non-zero when using a `proirityVector` from a trusted bidding signals fetch, and the interest group also has a `prioritySignals` field. See below for more details. +* `browserSignals.basePriority`: The `priority` field in the interest group, which may have been modified by a `setPriority()` call. +* `browserSignals.firstDotProductPriority`: The sparse dot product of the interest group's `priorityVector` and `prioritySignals`. Only non-zero when using a `priorityVector` from a trusted bidding signals fetch, and the interest group also has a `prioritySignals` field. See below for more details. * `browserSignals.ageInMinutes`: How long since the interest group was most recently joined, in minutes, as an integer. Guaranteed to be between 0 and 43200 (the number of minutes in 30 days, the maximum lifetime of an interest group), inclusive. -* `browserSignals.ageInMinutesMax60`: Same as `browserSignals.ageInMinutes`, but with a maximum value of 60, which is returned if the group is more than an hour old. +* `browserSignals.ageInMinutesMax60`: Same as `browserSignals.ageInMinutes`, but with a maximum value of 60. 60 is returned if the group is more than an hour old. * `browserSignals.ageInHoursMax24`: The interest group's age in hours, as an integer, with a maximum value of 24. Always non-negative. * `browserSignals.ageInDaysMax30`: The interest group's age in days, as an integer, with a maximum value of 30. Always non-negative. -If the resulting dot-product is negative, the interest group is immediately removed from an auction (note that if there's no `priorityVector`, interest groups with negative values currently are not filtered from auctions). After calculating new priorities as needed, and filtering out interest groups with negative calculated priorities, the `perBuyerGroupLimits` value is applied to all interest groups of a given owner, unless the interest group's `enableBiddingSignalsPrioritization` field is present and true. +If the resulting sparse dot product is negative, the interest group is immediately removed from the auction (note that if there's no `priorityVector`, interest groups with negative `priority` values currently are not filtered from auctions). After calculating new priorities as needed, and filtering out interest groups with negative calculated priorities, the `perBuyerGroupLimits` value is applied to all interest groups of a given owner, unless the interest group's `enableBiddingSignalsPrioritization` field is present and true. -If `enableBiddingSignalsPrioritization` is true, then rather than applying `perBuyerGroupLimits` immediately after the calculating the sparse dot product as desribed above, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the dot product of that `priorityVector` is again taken with a `prioritySignals` vector. The `prioritySignals` vector is the same as in the first calculation, except that that there's an addition `browserSignals.firstDotProductPriority` value, which is the result of multiplying the interest group's `priorityVector`, if present, with the `prioritySignals` of the auction. If this new dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. +If `enableBiddingSignalsPrioritization` is true, then rather than applying `perBuyerGroupLimits` immediately after the calculating the sparse dot product as described above, group limit enforcement is delayed until after fetching the trusted bidding signals. In this case, if the trusted bidding signals specify a per-interest-group `priorityVector` for an interest group, the sparse dot product of that `priorityVector` and the `prioritySignals` vector is calculated. The `prioritySignals` vector is the same as in the first calculation, except that that there's an addition `browserSignals.firstDotProductPriority` value, which is the result of multiplying the interest group's `priorityVector`, if present, with the `prioritySignals` of the auction. If this new dot product is negative, the interest group is removed from the auction. If there is no `priorityVector` for an interest group, the priority from earlier in the auction is used instead. Once all priorities have been calculated, then `perBuyerGroupLimits` is applied, and the auction continues as normal. -if `enableBiddingSignalsPrioritization` is false, then the `priorityVector` from the trusted bidding singals will still be multiplied by the `prioritySignals` as above, but it will only be used to skip the interest group if the result is less than 0. This parameter exists to improve performance - when it's false for all interest groups for a particular bidder in an auction, that bidder's interest groups can be filtered out before any bidding signals are fetched, reducing network usage and server load. +if `enableBiddingSignalsPrioritization` is false, then the `priorityVector` from the trusted bidding signals will still be multiplied by the `prioritySignals` as above, but it will only be used to skip the interest group if the result is less than 0. This parameter exists to improve performance - when it's false for all interest groups for a particular bidder in an auction, that bidder's interest groups can be filtered out before any bidding signals are fetched, reducing network usage and server load. ### 4. Browsers Render the Winning Ad From e109c0a995c10e6ebd54c509bc262821c5753778 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Wed, 5 Oct 2022 15:32:17 -0400 Subject: [PATCH 25/27] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index 8ef2d7f02..1d2ba6e8e 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -351,7 +351,7 @@ and the server must include the HTTP response header `X-fledge-bidding-signals-f The value of each key that an interest group has in its `trustedBiddingSignalsKeys` list will be passed from the `keys` dictionary to the interest group's generateBid() function as the `trustedBiddingSignals` parameter. Values missing from the JSON object will be set to null. If the JSON download fails, or there are no `trustedBiddingSignalsKeys` or `trustedBiddingSignalsUrl` in the interest group, then the `trustedBiddingSignals` argument to generateBid() will be null. -The `perInterestGroupData` dictionary contains optional data for interest groups whose names were included in the request URL. The `priorityVector` will be used to calculate the final priority for an interest group, if that interest group has `enableBiddingSignalsPrioritization` set to true in its definition. Otherwise, it's only used to filter out interest groups, if the result of multipling it by the `prioritySignals` is negative. See [Filtering and Prioritizing Interest Groups](#35-filtering-and-prioritizing-interest-groups) for more information. +The `perInterestGroupData` dictionary contains optional data for interest groups whose names were included in the request URL. The `priorityVector` will be used to calculate the final priority for an interest group, if that interest group has `enableBiddingSignalsPrioritization` set to true in its definition. Otherwise, it's only used to filter out interest groups, if the dot product with `prioritySignals` is negative. See [Filtering and Prioritizing Interest Groups](#35-filtering-and-prioritizing-interest-groups) for more information. Similarly, sellers may want to fetch information about a specific creative, e.g. the results of some out-of-band ad scanning system. This works in much the same way, with the base URL coming from the `trustedScoringSignalsUrl` property of the seller's auction configuration object. However, it has two sets of keys: "renderUrls=url1,url2,..." and "adComponentRenderUrls=url1,url2,..." for the main and adComponent renderUrls bids offered in the auction. It is up to the client how and whether to aggregate the fetches with the URLs of multiple bidders. The response to this request should be in the form: From fb7e7a6411353e02836338024ea4a3e205246bfb Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Mon, 24 Oct 2022 16:21:26 -0400 Subject: [PATCH 26/27] Update FLEDGE.md --- FLEDGE.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/FLEDGE.md b/FLEDGE.md index de8573800..793dfc4b5 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -541,6 +541,44 @@ If `enableBiddingSignalsPrioritization` is true, then rather than applying `perB if `enableBiddingSignalsPrioritization` is false, then the `priorityVector` from the trusted bidding signals will still be multiplied by the `prioritySignals` as above, but it will only be used to skip the interest group if the result is less than 0. This parameter exists to improve performance - when it's false for all interest groups for a particular bidder in an auction, that bidder's interest groups can be filtered out before any bidding signals are fetched, reducing network usage and server load. +For example, with the following interest groups and auction config: + +``` +auctionConfig = { + ..., + 'interestGroupBuyers': {'https://buyer1.com/'}, + 'perBuyerPrioritySignals': { + '\*': {'politics': 1}, + } +} + +interestGroup1 = { + 'owner': 'https://buyer1.com/', + 'name': 'NoPolitics', + 'priorityVector': {'politics': -1}, + ... +} + +interestGroup2 = { + 'owner': 'https://buyer1.com/', + 'name': 'BidFor240Minutes', + 'priorityVector': {'browserSignals.ageInMinutes': -1, 'browserSignals.one': 240}, + ... +} + +interestGroup3 = { + 'owner': 'https://buyer1.com/', + 'name': 'IgThatHasFilterDataFromServer', + 'trustedBiddingSignalsUrl': 'https://buyer1.com/bidder_signals', + ... +} +``` + +The `NoPolitics` interest group will not get a chance to bid, since the `AuctionConfig` has `politics` set to 1, and `NoPolitics` multiplies that by -1, giving it a priority of -1. + +The `BidFor240Minutes` interest group will have a positive priority if it was joined during the first 240 minutes, starting with 240 right after being joined, and working its way down to 0 at the 240 minute mark, after which it will have a negative priority and so will not bid. + +The 'FilterOnDataFromServer' will result in fetching `https://buyer1.com/bidder_signals?publisher=<...>&interest_groups=FilterOnDataFromServer` (possibly merged with other fetches), and then if that result has a `perInterestGroupData.IgThatHasFilterDataFromServer.priorityVector` object, then that is used just like the `priorityVector` field from the other two examples, except it's only used for filtering, not to set the priority, unless the group has a true `enableBiddingSignalsPrioritization` field. ### 4. Browsers Render the Winning Ad From 9c67b54fb4dbc74b793a177fba4c351b012472e2 Mon Sep 17 00:00:00 2001 From: Matt Menke Date: Thu, 10 Nov 2022 12:53:00 -0500 Subject: [PATCH 27/27] Apply suggestions from code review Co-authored-by: Paul Jensen --- FLEDGE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 793dfc4b5..ed44034f4 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -568,7 +568,7 @@ interestGroup2 = { interestGroup3 = { 'owner': 'https://buyer1.com/', - 'name': 'IgThatHasFilterDataFromServer', + 'name': 'FilterOnDataFromServer', 'trustedBiddingSignalsUrl': 'https://buyer1.com/bidder_signals', ... } @@ -578,7 +578,7 @@ The `NoPolitics` interest group will not get a chance to bid, since the `Auction The `BidFor240Minutes` interest group will have a positive priority if it was joined during the first 240 minutes, starting with 240 right after being joined, and working its way down to 0 at the 240 minute mark, after which it will have a negative priority and so will not bid. -The 'FilterOnDataFromServer' will result in fetching `https://buyer1.com/bidder_signals?publisher=<...>&interest_groups=FilterOnDataFromServer` (possibly merged with other fetches), and then if that result has a `perInterestGroupData.IgThatHasFilterDataFromServer.priorityVector` object, then that is used just like the `priorityVector` field from the other two examples, except it's only used for filtering, not to set the priority, unless the group has a true `enableBiddingSignalsPrioritization` field. +The `FilterOnDataFromServer` interest group will result in fetching `https://buyer1.com/bidder_signals?publisher=<...>&interest_groups=FilterOnDataFromServer,<...>`, and then if that result has a `perInterestGroupData.FilterOnDataFromServer.priorityVector` object, then that is used just like the `priorityVector` field from the other two examples, except that it's only used for filtering, not to set the priority (unless the group has a true `enableBiddingSignalsPrioritization` field). A [user defined function](https://github.com/privacysandbox/fledge-docs/blob/main/key_value_service_trust_model.md#support-for-user-defined-functions-udfs) could be used on the FLEDGE Key-Value server to calculate that `priorityVector` value, and hence to decide if `FilterOnDataFromServer`'s `generateBid()` method is invoked or if it's filtered out. ### 4. Browsers Render the Winning Ad