From 816d3262ab9524b9fca0ebfc1688600136872bd8 Mon Sep 17 00:00:00 2001 From: Tianyang Xu Date: Wed, 20 Nov 2024 21:00:36 +0000 Subject: [PATCH 1/6] Update FLEDGE explainer to add Trusted Signals KVv2 support --- FLEDGE.md | 46 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 14 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index e02d1a637..c96e08091 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -26,9 +26,11 @@ See [the Protected Audience API specification](https://wicg.github.io/turtledove - [2.5 Additional Trusted Signals (directFromSellerSignals)](#25-additional-trusted-signals-directfromsellersignals) - [2.5.1 Using Subresource Bundles](#251-using-subresource-bundles) - [2.5.2 Using Response Headers](#252-using-response-headers) - - [3. Buyers Provide Ads and Bidding Functions (BYOS for now)](#3-buyers-provide-ads-and-bidding-functions-byos-for-now) + - [3. Buyers Provide Ads and Bidding Functions](#3-buyers-provide-ads-and-bidding-functions) - [3.1 Fetching Real-Time Data from a Trusted Server](#31-fetching-real-time-data-from-a-trusted-server) - - [3.1.1 Cross-Origin Trusted Server Signals](#311-cross-origin-trusted-server-signals) + - [3.1.1 Trusted Signals Server with BYOS Model](#311-trusted-signals-server-with-byos-model) + - [3.1.2 Trusted Signals Server in TEE](#312-trusted-signals-server-in-tee) + - [3.1.3 Cross-Origin Trusted Server Signals](#313-cross-origin-trusted-server-signals) - [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) @@ -133,8 +135,9 @@ const myGroup = { 'executionMode': ..., 'trustedBiddingSignalsURL': ..., 'trustedBiddingSignalsKeys': ['key1', 'key2'], - 'trustedBiddingSignalsSlotSizeMode' : 'slot-size', - 'maxTrustedBiddingSignalsURLLength' : 10000, + 'trustedBiddingSignalsSlotSizeMode': 'slot-size', + 'maxTrustedBiddingSignalsURLLength': 10000, + 'trustedBiddingSignalsCoordinator': 'https://www.publickeyservice.com', 'userBiddingSignals': {...}, 'ads': [{renderUrl: shoesAd1, sizeGroup: 'group1', ...}, {renderUrl: shoesAd2, sizeGroup: 'group2', @@ -237,6 +240,14 @@ The `executionMode` attribute is optional, and may contain one of the following mode does not have the same limitations on what top-level sites can join or leave the interest group. +`trustedBiddingSignalsSlotSizeMode`, `maxTrustedBiddingSignalsURLLength`, and `trustedBiddingSignalsCoordinator` are three fields related to fetching trusted bidding signals. + +* `trustedBiddingSignalsSlotSizeMode` has three modes: none (default), slot-size, and all-slots-requested-sizes. These modes are used to attach the size information of ad slots. + +* `maxTrustedBiddingSignalsURLLength` is used to set the maximum URL length when constructing the URL for the trusted signals server in the BYOS (Bring Your Own Server) model. If set to 0 or not specified, the URL length is considered unlimited. + +* `trustedBiddingSignalsCoordinator` is another optional field used to specify where to obtain the public key which is used for encryption and decryption in communication. When this field is used, the fetch request will be sent to trusted signals server in TEE (Trust Execution Environment), and the value of maxTrustedBiddingSignalsURLLength is ignored. + The `ads` list contains the various ads that the interest group might show. Each entry is an object that must contain a `renderURL` property with the URL for the ad that would be shown. An ad may also have the following optional properties: * `adRenderId`: A short [DOMString](https://webidl.spec.whatwg.org/#idl-DOMString) up to 12 characters long serving as an identifier for this ad in this interest group. When this field is specified it will be sent instead of the full ad object for [B&A server auctions](https://github.com/WICG/turtledove/blob/main/FLEDGE_browser_bidding_and_auction_API.md). @@ -387,6 +398,7 @@ const myAuctionConfig = { 'decisionLogicURL': ..., 'trustedScoringSignalsURL': ..., 'maxTrustedScoringSignalsURLLength': 10000, + 'trustedScoringSignalsCoordinator': 'https://www.publickeyservice.com', 'interestGroupBuyers': ['https://www.example-dsp.com', 'https://buyer2.com', ...], 'auctionSignals': {...}, 'requestedSize': {'width': '100sw', 'height': '200px'}, @@ -450,6 +462,8 @@ else This will cause the browser to execute the appropriate bidding and auction logic inside a collection of dedicated worklets associated with the buyer and seller domains. The `auctionSignals`, `sellerSignals`, and `perBuyerSignals` values will be passed as arguments to the appropriate functions that run inside those worklets — the `auctionSignals` are made available to everyone, while the other signals are given only to one party. +`maxTrustedScoringSignalsURLLength` and `trustedScoringSignalsCoordinator` have the exact same functionality as `maxTrustedBiddingSignalsURLLength` and `trustedBiddingSignalsCoordinator`, as described in [1.2 Interest Group Attributes](#12-interest-group-attributes). + The optional `requestedSize` field recommends a frame size for the auction, which will be available to bidders in browser signals. This size should be specified in the same format as the sizes in the `adSizes` field of `joinAdInterestGroup`. For convenience, the returned fenced frame config will automatically populate a ``'s `width` and `height` attributes with the `requestedSize` when loaded, though the element's size attributes can still be modified if you want to change the element's container size. Bidders inside the auction may pick a different content size for the ad, and that resulting size will be visually scaled to fit inside the element's container size. `allSlotsRequestedSizes` may optionally be used to specify the size of all ad slots on the page, to be passed to each interest group's `trustedBuyerSignalsURL`, for interest groups that request it. All sizes in the list must be distinct. @@ -726,7 +740,7 @@ Like `directFromSellerSignals`, `directFromSellerSignalsHeaderAdSlot` may be pas The signals are only guaranteed to be available to `navigator.runAdAuction()` after the `fetch()` promise has resolved. Therefore, to avoid races, either `runAdAuction()` should be called after resolving the `fetch()` promise, or `directFromSellerSignalsHeaderAdSlot` should be passed a promise that only resolves after the `fetch()` promise resolves. -### 3. Buyers Provide Ads and Bidding Functions (BYOS for now) +### 3. Buyers Provide Ads and Bidding Functions Interest groups are used by their owners to bid in on-device auctions. We refer to each party bidding in an auction as a _buyer_. The buyer might be an advertiser who is also an interest group owner themselves, or a DSP that owns an interest group and acts on an advertiser's behalf. @@ -745,7 +759,13 @@ Buyers have three basic jobs in the on-device ad auction: #### 3.1 Fetching Real-Time Data from a Trusted Server -Buyers may want to make on-device decisions that take into account real-time data (for example, the remaining budget of an ad campaign). This need can be met using the interest group's `trustedBiddingSignalsURL`, `trustedBiddingSignalsKeys`, and, optionally, `trustedBiddingSignalsSlotSizeMode` and `maxTrustedBiddingSignalsURLLength` fields. Once a seller initiates an on-device auction on a publisher page, the browser checks each participating interest group for these fields, and makes an uncredentialed (cookieless) HTTP fetch to a URL of the form: +Buyers may want to make on-device decisions that take into account real-time data (for example, the remaining budget of an ad campaign). This need can be met using the interest group's `trustedBiddingSignalsURL`, `trustedBiddingSignalsKeys`, and, optionally, `trustedBiddingSignalsSlotSizeMode`, `maxTrustedBiddingSignalsURLLength` and `trustedBiddingSignalsCoordinator` 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 Key-Value server with the choice of BYOS (Bring Your Own Server) or Trusted Server in TEE (Trust Execution Environment). + +As [noted in the key value trust model](https://github.com/privacysandbox/fledge-docs/blob/main/key_value_service_trust_model.md), the key value service is publicly queryable, so to prevent potentially leaking user information, keys should be either: not individually identifying (e.g. applying to many people, perhaps to all people who visited an advertiser page and that an ad campaign might show to) or unguessable (e.g. using random identifiers that are assigned at interest group join time and known only to the caller of joinAdInterestGroup). They should not be uniquely identifying and use guessable keys (e.g. hashed email address, name, or phone number). + +##### 3.1.1 Trusted Signals Server with BYOS Model + +If `trustedBiddingSignalsCoordinator` is not presented, it indicates that the trusted bidding signals will be fetched from a BYOS server. The fetching URL will be as follows: https://www.kv-server.example/getvalues?hostname=publisher.com&keys=key1,key2&interestGroupNames=name1,name2&experimentGroupId=12345&slotSize=100,200 @@ -781,7 +801,7 @@ The `perInterestGroupData` dictionary contains optional data for interest groups The `updateIfOlderThanMs` optional field specifies that the interest group should be updated via the `updateURL` mechanism (see the [interest group attributes](#12-interest-group-attributes) section) if the interest group hasn't been joined or updated in a duration of time exceeding `updateIfOlderThanMs` milliseconds. Updates that ended in failure, either parse or network failure, are not considered to increment the last update or join time. An `updateIfOlderThanMs` that's less than 10 minutes will be clamped to 10 minutes. -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 as [`trustedBiddingSignalsURL`](#31-fetching-real-time-data-from-a-trusted-server), with the base URL coming from the `trustedScoringSignalsURL` property of the seller's auction configuration object. The parameter `experimentGroupId` comes from `sellerExperimentGroupId` in the auction configuration if provided. However, the URL has two sets of keys: "renderUrls=url1,url2,..." and "adComponentRenderUrls=url1,url2,..." for the main and adComponent renderURLs bids offered in the auction. Note that the query params use "Urls" instead of "URLs". It is up to the client how and whether to aggregate the fetches with the URLs of multiple bidders. +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 as [`trustedBiddingSignalsURL`](#311-trusted-signals-server-with-byos-model). If `trustedScoringSignalsCoordinator` is not presented, it will send the trusted scoring signals fetch request to BYOS server. The request base URL is set from the `trustedScoringSignalsURL` property of the seller's auction configuration object. The parameter `experimentGroupId` comes from `sellerExperimentGroupId` in the auction configuration if provided. However, the URL has two sets of keys: "renderUrls=url1,url2,..." and "adComponentRenderUrls=url1,url2,..." for the main and adComponent renderURLs bids offered in the auction. Note that the query params use "Urls" instead of "URLs". It is up to the client how and whether to aggregate the fetches with the URLs of multiple bidders. Similarly to `trustedBiddingSignalsURL`, scoring signals requests may also be coalesced across a certain number of bids that share a `trustedScoringSignalsURL`. The number of bids in a single request is limited by the auction configuration's `maxTrustedScoringSignalsURLLength` field. For example, if an auction configuration has a `maxTrustedScoringSignalsURLLength` of 1000, it means that the length of each trusted scoring signals request URL for this auction cannot exceed 1000 characters. If an auction configuration wants an infinite length for the request URL, it can specify 0 for the `maxTrustedScoringSignalsURLLength`. @@ -810,18 +830,16 @@ The value of `trustedScoringSignals` passed to the seller's `scoreAd()` function } ``` -_As a temporary mechanism_ during the First Experiment timeframe, the buyer and seller can fetch these bidding signals from any server, including one they operate themselves (a "Bring Your Own Server" model). However, in the final version after the removal of third-party cookies, the request will only be sent to a trusted key-value-type server. Because the server is trusted, there is no k-anonymity constraint on this request. The browser needs to trust that the server's return value for each key will be based only on that key and the hostname, and that the server does no event-level logging and has no other side effects based on these requests. +Either trusted server may optionally include a numeric `Data-Version` header on the response to indicate the state of the data that generated this response, which will then be available in bid generation/scoring and reporting. This version number should not depend on any properties of the request, only the state of the server. Ideally, the number would only increment and at any time would be identical across all servers in a fleet. In practice a small amount of skew is permitted for operational reasons, including propagation delays, staged rollouts, and emergency rollbacks. The version number should be formatted with only the digits `[0-9]` with no leading `0`s and fit in a 32-bit unsigned integer. -As [noted in the key value trust model](https://github.com/privacysandbox/fledge-docs/blob/main/key_value_service_trust_model.md#:~:text=Note%20that%20the%20values%20being%20stored%20in%20the%20key/value%20service%20are%20loaded%20by%20adtechs%20and%20expected%20to%20be%20publicly%20visible%20to%20clients.%20These%20are%20therefore%20not%20confidential.), the key value service is publicly queryable, so to prevent potentially leaking user information, keys should be either: not individually identifying (e.g. applying to many people, perhaps to all people who visited an advertiser page and that an ad campaign might show to) or unguessable (e.g. using random identifiers that are assigned at interest group join time and known only to the caller of joinAdInterestGroup). They should not be uniquely identifying and use guessable keys (e.g. hashed email address, name, or phone number). -Either trusted server may optionally include a numeric `Data-Version` header on the response to indicate the state of the data that generated this response, which will then be available in bid generation/scoring and reporting. This version number should not depend on any properties of the request, only the state of the server. Ideally, the number would only increment and at any time would be identical across all servers in a fleet. In practice a small amount of skew is permitted for operational reasons, including propagation delays, staged rollouts, and emergency rollbacks. The version number should be formatted with only the digits `[0-9]` with no leading `0`s and fit in a 32-bit unsigned integer. +##### 3.1.2 Trusted Signals Server in TEE -For detailed specification and explainers of the trusted key-value server, see also the following: +If `trustedBiddingSignalsCoordinator` or `trustedScoringSignalsCoordinator` is presented, the request will be sent to a trusted key-value-type server. Because the server is trusted, there is no k-anonymity constraint on this request. The browser needs to trust that the server's return value for each key will be based only on that key and the hostname, and that the server does no event-level logging and has no other side effects based on these requests. -- [FLEDGE Key/Value Server APIs Explainer](https://github.com/WICG/turtledove/blob/master/FLEDGE_Key_Value_Server_API.md) -- [FLEDGE Key/Value Server Trust Model Explainer](https://github.com/privacysandbox/fledge-docs/blob/main/key_value_service_trust_model.md) +Once an on-device auction is initiated, the browser will make a HTTP POST fetch to a base URL such as `https://www.kv-server.example/getvalues`, which comes from the interest group's `trustedBiddingSignalsURL` or auction config's `trustedScoringSignalsURL`. All the other information for the trusted signals will be put into the request body, with CBOR encoding and encryption as decribed in [FLEDGE Key/Value Server APIs Explainer](https://github.com/WICG/turtledove/blob/master/FLEDGE_Key_Value_Server_API.md). -##### 3.1.1 Cross-Origin Trusted Server Signals +##### 3.1.3 Cross-Origin Trusted Server Signals If the key-value server is on a different origin than the corresponding script, additional steps are needed to ensure that sensitive information is not inappropriately leaked to, or is manipulated by, From 059b210b1f71697d5fca8d8ecbff14097bf2f767 Mon Sep 17 00:00:00 2001 From: Tianyang Xu <40476544+xtlsheep@users.noreply.github.com> Date: Tue, 26 Nov 2024 13:03:55 -0500 Subject: [PATCH 2/6] Update FLEDGE.md --- FLEDGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FLEDGE.md b/FLEDGE.md index c96e08091..e653e2fff 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -835,7 +835,7 @@ Either trusted server may optionally include a numeric `Data-Version` header on ##### 3.1.2 Trusted Signals Server in TEE -If `trustedBiddingSignalsCoordinator` or `trustedScoringSignalsCoordinator` is presented, the request will be sent to a trusted key-value-type server. Because the server is trusted, there is no k-anonymity constraint on this request. The browser needs to trust that the server's return value for each key will be based only on that key and the hostname, and that the server does no event-level logging and has no other side effects based on these requests. +If `trustedBiddingSignalsCoordinator` or `trustedScoringSignalsCoordinator` is presented, the request will be sent in a version 2 protocol. Because the server is trusted, there is no k-anonymity constraint on this request. The browser needs to trust that the server's return value for each key will be based only on that key and the hostname, and that the server does no event-level logging and has no other side effects based on these requests. Once an on-device auction is initiated, the browser will make a HTTP POST fetch to a base URL such as `https://www.kv-server.example/getvalues`, which comes from the interest group's `trustedBiddingSignalsURL` or auction config's `trustedScoringSignalsURL`. All the other information for the trusted signals will be put into the request body, with CBOR encoding and encryption as decribed in [FLEDGE Key/Value Server APIs Explainer](https://github.com/WICG/turtledove/blob/master/FLEDGE_Key_Value_Server_API.md). From ac3cf90daa0467d2ac45014154757682ed324be7 Mon Sep 17 00:00:00 2001 From: Tianyang Xu <40476544+xtlsheep@users.noreply.github.com> Date: Tue, 3 Dec 2024 00:57:14 -0500 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Paul Jensen --- FLEDGE.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index e653e2fff..0595aa800 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -240,13 +240,13 @@ The `executionMode` attribute is optional, and may contain one of the following mode does not have the same limitations on what top-level sites can join or leave the interest group. -`trustedBiddingSignalsSlotSizeMode`, `maxTrustedBiddingSignalsURLLength`, and `trustedBiddingSignalsCoordinator` are three fields related to fetching trusted bidding signals. +`trustedBiddingSignalsSlotSizeMode`, `maxTrustedBiddingSignalsURLLength`, and `trustedBiddingSignalsCoordinator` are three optional fields related to fetching trusted bidding signals. -* `trustedBiddingSignalsSlotSizeMode` has three modes: none (default), slot-size, and all-slots-requested-sizes. These modes are used to attach the size information of ad slots. +* `trustedBiddingSignalsSlotSizeMode` has three modes: `none` (default), `slot-size`, and `all-slots-requested-sizes`. These modes are used to attach the size information of ad slots. See [3.1 Fetching Real-Time Data from a Trusted Server](#31-fetching-real-time-data-from-a-trusted-server) for more information. -* `maxTrustedBiddingSignalsURLLength` is used to set the maximum URL length when constructing the URL for the trusted signals server in the BYOS (Bring Your Own Server) model. If set to 0 or not specified, the URL length is considered unlimited. +* `maxTrustedBiddingSignalsURLLength` is used to set the maximum URL length when constructing the URL for the trusted signals server in the BYOS (Bring Your Own Server) model. If set to 0 or not specified, the URL length is considered unlimited. See [3.1 Fetching Real-Time Data from a Trusted Server](#31-fetching-real-time-data-from-a-trusted-server) for more information. -* `trustedBiddingSignalsCoordinator` is another optional field used to specify where to obtain the public key which is used for encryption and decryption in communication. When this field is used, the fetch request will be sent to trusted signals server in TEE (Trust Execution Environment), and the value of maxTrustedBiddingSignalsURLLength is ignored. +* `trustedBiddingSignalsCoordinator` is used to specify where to obtain the public key used for encryption and decryption in communication with a trusted bidding signal server running in a Trust Execution Environment (TEE). When this field is specified, the request will be sent to a trusted bidding signals server running in a TEE, and the value of `maxTrustedBiddingSignalsURLLength` is ignored. The `ads` list contains the various ads that the interest group might show. Each entry is an object that must contain a `renderURL` property with the URL for the ad that would be shown. An ad may also have the following optional properties: @@ -462,7 +462,7 @@ else This will cause the browser to execute the appropriate bidding and auction logic inside a collection of dedicated worklets associated with the buyer and seller domains. The `auctionSignals`, `sellerSignals`, and `perBuyerSignals` values will be passed as arguments to the appropriate functions that run inside those worklets — the `auctionSignals` are made available to everyone, while the other signals are given only to one party. -`maxTrustedScoringSignalsURLLength` and `trustedScoringSignalsCoordinator` have the exact same functionality as `maxTrustedBiddingSignalsURLLength` and `trustedBiddingSignalsCoordinator`, as described in [1.2 Interest Group Attributes](#12-interest-group-attributes). +`maxTrustedScoringSignalsURLLength` and `trustedScoringSignalsCoordinator` have the same functionality as `maxTrustedBiddingSignalsURLLength` and `trustedBiddingSignalsCoordinator`, as described in [1.2 Interest Group Attributes](#12-interest-group-attributes). The optional `requestedSize` field recommends a frame size for the auction, which will be available to bidders in browser signals. This size should be specified in the same format as the sizes in the `adSizes` field of `joinAdInterestGroup`. For convenience, the returned fenced frame config will automatically populate a ``'s `width` and `height` attributes with the `requestedSize` when loaded, though the element's size attributes can still be modified if you want to change the element's container size. Bidders inside the auction may pick a different content size for the ad, and that resulting size will be visually scaled to fit inside the element's container size. @@ -759,13 +759,13 @@ Buyers have three basic jobs in the on-device ad auction: #### 3.1 Fetching Real-Time Data from a Trusted Server -Buyers may want to make on-device decisions that take into account real-time data (for example, the remaining budget of an ad campaign). This need can be met using the interest group's `trustedBiddingSignalsURL`, `trustedBiddingSignalsKeys`, and, optionally, `trustedBiddingSignalsSlotSizeMode`, `maxTrustedBiddingSignalsURLLength` and `trustedBiddingSignalsCoordinator` 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 Key-Value server with the choice of BYOS (Bring Your Own Server) or Trusted Server in TEE (Trust Execution Environment). - -As [noted in the key value trust model](https://github.com/privacysandbox/fledge-docs/blob/main/key_value_service_trust_model.md), the key value service is publicly queryable, so to prevent potentially leaking user information, keys should be either: not individually identifying (e.g. applying to many people, perhaps to all people who visited an advertiser page and that an ad campaign might show to) or unguessable (e.g. using random identifiers that are assigned at interest group join time and known only to the caller of joinAdInterestGroup). They should not be uniquely identifying and use guessable keys (e.g. hashed email address, name, or phone number). +Buyers may want to make on-device decisions that take into account real-time data (for example, the remaining budget of an ad campaign). This need can be met using the interest group's `trustedBiddingSignalsURL`, `trustedBiddingSignalsKeys`, and, optionally, `trustedBiddingSignalsSlotSizeMode`, `maxTrustedBiddingSignalsURLLength` and `trustedBiddingSignalsCoordinator` 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 Key-Value server. +_As a temporary mechanism_ during the First Experiment timeframe, the buyer and seller can fetch these bidding signals from any server, including one they operate themselves (a "Bring Your Own Server" model). However, in the final version after the removal of third-party cookies, the request will only be sent to a trusted key-value-type server. Because the server is trusted, there is no k-anonymity constraint on this request. The browser needs to trust that the server's return value for each key will be based only on that key and the hostname, and that the server does no event-level logging and has no other side effects based on these requests. +As [noted in the key value trust model](https://github.com/privacysandbox/fledge-docs/blob/main/key_value_service_trust_model.md#:~:text=Note%20that%20the%20values%20being%20stored%20in%20the%20key/value%20service%20are%20loaded%20by%20adtechs%20and%20expected%20to%20be%20publicly%20visible%20to%20clients.%20These%20are%20therefore%20not%20confidential.), the key value service is publicly queryable, so to prevent potentially leaking user information, keys should be either: not individually identifying (e.g. applying to many people, perhaps to all people who visited an advertiser page and that an ad campaign might show to) or unguessable (e.g. using random identifiers that are assigned at interest group join time and known only to the caller of joinAdInterestGroup). They should not be uniquely identifying and use guessable keys (e.g. hashed email address, name, or phone number). ##### 3.1.1 Trusted Signals Server with BYOS Model -If `trustedBiddingSignalsCoordinator` is not presented, it indicates that the trusted bidding signals will be fetched from a BYOS server. The fetching URL will be as follows: +If `trustedBiddingSignalsCoordinator` is not present in the interest group, the bidding signals will be fetched from a BYOS server. The fetched URL will be of the form: https://www.kv-server.example/getvalues?hostname=publisher.com&keys=key1,key2&interestGroupNames=name1,name2&experimentGroupId=12345&slotSize=100,200 @@ -801,7 +801,7 @@ The `perInterestGroupData` dictionary contains optional data for interest groups The `updateIfOlderThanMs` optional field specifies that the interest group should be updated via the `updateURL` mechanism (see the [interest group attributes](#12-interest-group-attributes) section) if the interest group hasn't been joined or updated in a duration of time exceeding `updateIfOlderThanMs` milliseconds. Updates that ended in failure, either parse or network failure, are not considered to increment the last update or join time. An `updateIfOlderThanMs` that's less than 10 minutes will be clamped to 10 minutes. -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 as [`trustedBiddingSignalsURL`](#311-trusted-signals-server-with-byos-model). If `trustedScoringSignalsCoordinator` is not presented, it will send the trusted scoring signals fetch request to BYOS server. The request base URL is set from the `trustedScoringSignalsURL` property of the seller's auction configuration object. The parameter `experimentGroupId` comes from `sellerExperimentGroupId` in the auction configuration if provided. However, the URL has two sets of keys: "renderUrls=url1,url2,..." and "adComponentRenderUrls=url1,url2,..." for the main and adComponent renderURLs bids offered in the auction. Note that the query params use "Urls" instead of "URLs". It is up to the client how and whether to aggregate the fetches with the URLs of multiple bidders. +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 as [`trustedBiddingSignalsURL`](#311-trusted-signals-server-with-byos-model). If `trustedScoringSignalsCoordinator` is not present in the auction config, it will send the scoring signals fetch request to a BYOS server. The request base URL is set from the `trustedScoringSignalsURL` property of the seller's auction configuration object. The parameter `experimentGroupId` comes from `sellerExperimentGroupId` in the auction configuration if provided. However, the URL has two sets of keys: "renderUrls=url1,url2,..." and "adComponentRenderUrls=url1,url2,..." for the main and adComponent renderURLs bids offered in the auction. Note that the query params use "Urls" instead of "URLs". It is up to the client how and whether to aggregate the fetches with the URLs of multiple bidders. Similarly to `trustedBiddingSignalsURL`, scoring signals requests may also be coalesced across a certain number of bids that share a `trustedScoringSignalsURL`. The number of bids in a single request is limited by the auction configuration's `maxTrustedScoringSignalsURLLength` field. For example, if an auction configuration has a `maxTrustedScoringSignalsURLLength` of 1000, it means that the length of each trusted scoring signals request URL for this auction cannot exceed 1000 characters. If an auction configuration wants an infinite length for the request URL, it can specify 0 for the `maxTrustedScoringSignalsURLLength`. @@ -833,11 +833,15 @@ The value of `trustedScoringSignals` passed to the seller's `scoreAd()` function Either trusted server may optionally include a numeric `Data-Version` header on the response to indicate the state of the data that generated this response, which will then be available in bid generation/scoring and reporting. This version number should not depend on any properties of the request, only the state of the server. Ideally, the number would only increment and at any time would be identical across all servers in a fleet. In practice a small amount of skew is permitted for operational reasons, including propagation delays, staged rollouts, and emergency rollbacks. The version number should be formatted with only the digits `[0-9]` with no leading `0`s and fit in a 32-bit unsigned integer. +For detailed specification and explainers of the trusted key-value server, see also the following: + +- [FLEDGE Key/Value Server APIs Explainer](https://github.com/WICG/turtledove/blob/master/FLEDGE_Key_Value_Server_API.md) +- [FLEDGE Key/Value Server Trust Model Explainer](https://github.com/privacysandbox/fledge-docs/blob/main/key_value_service_trust_model.md) ##### 3.1.2 Trusted Signals Server in TEE -If `trustedBiddingSignalsCoordinator` or `trustedScoringSignalsCoordinator` is presented, the request will be sent in a version 2 protocol. Because the server is trusted, there is no k-anonymity constraint on this request. The browser needs to trust that the server's return value for each key will be based only on that key and the hostname, and that the server does no event-level logging and has no other side effects based on these requests. +If `trustedBiddingSignalsCoordinator` or `trustedScoringSignalsCoordinator` is specified, the bidding or scoring signals request will be sent to a trusted key-value-type server running in a TEE using [the version 2 protocol](https://github.com/WICG/turtledove/blob/main/FLEDGE_Key_Value_Server_API.md#query-api-version-2). The browser can trust that the server's return value for each key will be based only on that key and the hostname, and that the server does no event-level logging and has no other side effects based on these requests. -Once an on-device auction is initiated, the browser will make a HTTP POST fetch to a base URL such as `https://www.kv-server.example/getvalues`, which comes from the interest group's `trustedBiddingSignalsURL` or auction config's `trustedScoringSignalsURL`. All the other information for the trusted signals will be put into the request body, with CBOR encoding and encryption as decribed in [FLEDGE Key/Value Server APIs Explainer](https://github.com/WICG/turtledove/blob/master/FLEDGE_Key_Value_Server_API.md). +Once an on-device auction is initiated, the browser will make an HTTP POST request to a base URL such as `https://www.kv-server.example/getvalues`, which comes from the interest group's `trustedBiddingSignalsURL` or auction config's `trustedScoringSignalsURL`. The other information for the trusted signals request will be put into the request body, with CBOR encoding and HPKE encryption as described in [FLEDGE Key/Value Server APIs Explainer](https://github.com/WICG/turtledove/blob/master/FLEDGE_Key_Value_Server_API.md). ##### 3.1.3 Cross-Origin Trusted Server Signals From 34c9b17281f0c159e04c62d005a11fb136e5c95a Mon Sep 17 00:00:00 2001 From: Tianyang Xu <40476544+xtlsheep@users.noreply.github.com> Date: Tue, 3 Dec 2024 00:58:53 -0500 Subject: [PATCH 4/6] Apply suggestions from code review --- FLEDGE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 0595aa800..55d7e6267 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -242,7 +242,7 @@ The `executionMode` attribute is optional, and may contain one of the following `trustedBiddingSignalsSlotSizeMode`, `maxTrustedBiddingSignalsURLLength`, and `trustedBiddingSignalsCoordinator` are three optional fields related to fetching trusted bidding signals. -* `trustedBiddingSignalsSlotSizeMode` has three modes: `none` (default), `slot-size`, and `all-slots-requested-sizes`. These modes are used to attach the size information of ad slots. See [3.1 Fetching Real-Time Data from a Trusted Server](#31-fetching-real-time-data-from-a-trusted-server) for more information. +* `trustedBiddingSignalsSlotSizeMode` has three modes: `none` (default), `slot-size`, and `all-slots-requested-sizes`. These modes are used to attach the size information of ad slots. See [3.1 Fetching Real-Time Data from a Trusted Server](#31-fetching-real-time-data-from-a-trusted-server) for more information. * `maxTrustedBiddingSignalsURLLength` is used to set the maximum URL length when constructing the URL for the trusted signals server in the BYOS (Bring Your Own Server) model. If set to 0 or not specified, the URL length is considered unlimited. See [3.1 Fetching Real-Time Data from a Trusted Server](#31-fetching-real-time-data-from-a-trusted-server) for more information. @@ -606,7 +606,7 @@ The function gets called once for each candidate ad in the auction. The argumen * crossOriginTrustedSignals: like `trustedScoringSignals`, but used when the server is cross-origin to the seller script. The value is an object that has as a key the trusted server's origin, e.g. `"https://example.org"`, and as value an object in format `trustedScoringSignals` uses. See - [3.1.1 Cross-Origin Trusted Server Signals](#311-cross-origin-trusted-server-signals) for more + [3.1.3 Cross-Origin Trusted Server Signals](#313-cross-origin-trusted-server-signals) for more details. The output of `scoreAd()` is an object with the following fields: @@ -977,7 +977,7 @@ The arguments to `generateBid()` are: cross-origin to the buyer's script. The value is an object that has as a key the trusted server's origin, e.g. `"https://www.kv-server.example"`, and as value an object in format `trustedBiddingSignals` uses. See - [3.1.1 Cross-Origin Trusted Server Signals](#311-cross-origin-trusted-server-signals) for more + [3.1.3 Cross-Origin Trusted Server Signals](#313-cross-origin-trusted-server-signals) for more details. In the case of component auctions, an interest group's `generateBid()` function will be invoked in all component auctions for which it qualifies, though the `bidCount` value passed to future auctions will only be incremented by one for participation in that auction as a whole. From 700f073a78bc4521fbd7614cd30f983626166f4f Mon Sep 17 00:00:00 2001 From: Tianyang Xu <40476544+xtlsheep@users.noreply.github.com> Date: Tue, 3 Dec 2024 15:56:59 -0500 Subject: [PATCH 5/6] Update FLEDGE.md --- FLEDGE.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/FLEDGE.md b/FLEDGE.md index 55d7e6267..ea2618de5 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -760,7 +760,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`, `trustedBiddingSignalsKeys`, and, optionally, `trustedBiddingSignalsSlotSizeMode`, `maxTrustedBiddingSignalsURLLength` and `trustedBiddingSignalsCoordinator` 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 Key-Value server. -_As a temporary mechanism_ during the First Experiment timeframe, the buyer and seller can fetch these bidding signals from any server, including one they operate themselves (a "Bring Your Own Server" model). However, in the final version after the removal of third-party cookies, the request will only be sent to a trusted key-value-type server. Because the server is trusted, there is no k-anonymity constraint on this request. The browser needs to trust that the server's return value for each key will be based only on that key and the hostname, and that the server does no event-level logging and has no other side effects based on these requests. + +_As a temporary mechanism_ during the First Experiment timeframe, the buyer and seller can fetch these bidding signals from any server, including one they operate themselves (a "Bring Your Own Server" model). However, in the final version after the removal of third-party cookies, the request will only be sent to a trusted key-value-type server. Because the server is trusted, there is no k-anonymity constraint on this request. The trusted key-value-type server follows this [trust model](https://github.com/privacysandbox/protected-auction-services-docs/blob/main/key_value_service_trust_model.md) and uses [this protocol](https://github.com/WICG/turtledove/blob/main/FLEDGE_Key_Value_Server_API.md). + As [noted in the key value trust model](https://github.com/privacysandbox/fledge-docs/blob/main/key_value_service_trust_model.md#:~:text=Note%20that%20the%20values%20being%20stored%20in%20the%20key/value%20service%20are%20loaded%20by%20adtechs%20and%20expected%20to%20be%20publicly%20visible%20to%20clients.%20These%20are%20therefore%20not%20confidential.), the key value service is publicly queryable, so to prevent potentially leaking user information, keys should be either: not individually identifying (e.g. applying to many people, perhaps to all people who visited an advertiser page and that an ad campaign might show to) or unguessable (e.g. using random identifiers that are assigned at interest group join time and known only to the caller of joinAdInterestGroup). They should not be uniquely identifying and use guessable keys (e.g. hashed email address, name, or phone number). ##### 3.1.1 Trusted Signals Server with BYOS Model @@ -839,7 +841,7 @@ For detailed specification and explainers of the trusted key-value server, see a - [FLEDGE Key/Value Server Trust Model Explainer](https://github.com/privacysandbox/fledge-docs/blob/main/key_value_service_trust_model.md) ##### 3.1.2 Trusted Signals Server in TEE -If `trustedBiddingSignalsCoordinator` or `trustedScoringSignalsCoordinator` is specified, the bidding or scoring signals request will be sent to a trusted key-value-type server running in a TEE using [the version 2 protocol](https://github.com/WICG/turtledove/blob/main/FLEDGE_Key_Value_Server_API.md#query-api-version-2). The browser can trust that the server's return value for each key will be based only on that key and the hostname, and that the server does no event-level logging and has no other side effects based on these requests. +If `trustedBiddingSignalsCoordinator` or `trustedScoringSignalsCoordinator` is specified, the bidding or scoring signals request will be sent to a trusted key-value-type server running in a TEE using [the version 2 protocol](https://github.com/WICG/turtledove/blob/main/FLEDGE_Key_Value_Server_API.md#query-api-version-2). Once an on-device auction is initiated, the browser will make an HTTP POST request to a base URL such as `https://www.kv-server.example/getvalues`, which comes from the interest group's `trustedBiddingSignalsURL` or auction config's `trustedScoringSignalsURL`. The other information for the trusted signals request will be put into the request body, with CBOR encoding and HPKE encryption as described in [FLEDGE Key/Value Server APIs Explainer](https://github.com/WICG/turtledove/blob/master/FLEDGE_Key_Value_Server_API.md). From 2dd6b034a520775ff28f6eaf35de88c627a2b7be Mon Sep 17 00:00:00 2001 From: Tianyang Xu <40476544+xtlsheep@users.noreply.github.com> Date: Wed, 11 Dec 2024 13:30:14 -0500 Subject: [PATCH 6/6] 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 ea2618de5..cc2bbc938 100644 --- a/FLEDGE.md +++ b/FLEDGE.md @@ -462,7 +462,7 @@ else This will cause the browser to execute the appropriate bidding and auction logic inside a collection of dedicated worklets associated with the buyer and seller domains. The `auctionSignals`, `sellerSignals`, and `perBuyerSignals` values will be passed as arguments to the appropriate functions that run inside those worklets — the `auctionSignals` are made available to everyone, while the other signals are given only to one party. -`maxTrustedScoringSignalsURLLength` and `trustedScoringSignalsCoordinator` have the same functionality as `maxTrustedBiddingSignalsURLLength` and `trustedBiddingSignalsCoordinator`, as described in [1.2 Interest Group Attributes](#12-interest-group-attributes). +`maxTrustedScoringSignalsURLLength` and `trustedScoringSignalsCoordinator` have the same functionality as `maxTrustedBiddingSignalsURLLength` and `trustedBiddingSignalsCoordinator`, as described in [1.2 Interest Group Attributes](#12-interest-group-attributes), but affect the seller's trusted scoring signals fetch as opposed to the trusted bidding signals fetch. The optional `requestedSize` field recommends a frame size for the auction, which will be available to bidders in browser signals. This size should be specified in the same format as the sizes in the `adSizes` field of `joinAdInterestGroup`. For convenience, the returned fenced frame config will automatically populate a ``'s `width` and `height` attributes with the `requestedSize` when loaded, though the element's size attributes can still be modified if you want to change the element's container size. Bidders inside the auction may pick a different content size for the ad, and that resulting size will be visually scaled to fit inside the element's container size.