From 25ee9fd45ae71a14788437fda9972123aaf25826 Mon Sep 17 00:00:00 2001 From: "Benjamin \"Russ\" Hamilton" Date: Mon, 30 Sep 2024 11:00:07 -0400 Subject: [PATCH] [spec] Add Bidding and auction payload customization support (#1274) * Add payload optimization * Add missing = * Add constraint on request size * Apply suggestions from code review Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com> * Address comments * Address comments * Add domintro for AdAuctionDataConfig * Fix missing description * Apply suggestions from code review Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com> * Describe values of {{AdAuctionDataConfig/perBuyerConfig}} * Fix filtering logic --------- Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com> --- spec.bs | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 119 insertions(+), 4 deletions(-) diff --git a/spec.bs b/spec.bs index 649d35161..20832711c 100644 --- a/spec.bs +++ b/spec.bs @@ -2992,17 +2992,53 @@ partial interface Navigator { Promise getInterestGroupAdAuctionData(AdAuctionDataConfig config); }; +dictionary AdAuctionData { + required Uint8Array request; + required USVString requestId; +}; + + + dictionary AdAuctionDataConfig { required USVString seller; required USVString coordinatorOrigin; + unsigned long requestSize; + record<USVString, AdAuctionDataBuyerConfig> perBuyerConfig; }; + -dictionary AdAuctionData { - required Uint8Array request; - required USVString requestId; +
+
{{AdAuctionDataConfig/seller}} +
The seller that will be used as the {{AuctionAdConfig/seller}} in the + following {{AuctionAdConfig}} passed to {{Window/navigator}}.{{Navigator/runAdAuction()}}. +
{{AdAuctionDataConfig/coordinatorOrigin}} +
The origin of the coordinator hosting public encryption keys for the server + running the ad auction. The [=origin/scheme=] must be "`https`". An implementation + may select which coordinators are acceptable. +
{{AdAuctionDataConfig/requestSize}} +
The desired size for the returned {{AdAuctionData/request}}. If any buyers are specified in + {{AdAuctionDataConfig/perBuyerConfig}}, this will be the exact size of the returned {{AdAuctionData/request}}. + Otherwise the returned {{AdAuctionData/request}}'s size will be at most the + {{AdAuctionDataConfig/requestSize}}. +
{{AdAuctionDataConfig/perBuyerConfig}} +
[=map/Keys=] are [=serialization of an origin|serialized origins=] of + buyers that should be included in the returned request. [=map/Values=] are + {{AdAuctionDataBuyerConfig}} for that buyer. +
+ + +dictionary AdAuctionDataBuyerConfig { + unsigned long targetSize; }; +
+
{{AdAuctionDataBuyerConfig/targetSize}} +
The size of the request to allocate for this buyer. Required when + {{AdAuctionDataConfig}}'s {{AdAuctionDataConfig/requestSize}} is not + specified. +
+ A server auction interest group is a [=struct=] with the following [=struct/items=]:
: name @@ -3019,6 +3055,9 @@ A server auction interest group is a [=struct=] with the following [= from the [=interest group/ad components=] field. : browser signals :: A [=server auction browser signals=]. + : priority + :: A {{double}}. Used to select which interest groups for a given buyer are excluded + from the serialized request due to space limitations.
A server auction browser signals is a [=struct=] with the following [=struct/items=]: @@ -3121,11 +3160,12 @@ A server auction reporting info is a [=struct=] with the following [=
-The getInterestGroupAdAuctionData(|config|) method steps are: +The getInterestGroupAdAuctionData(|configIDL|) method steps are: 1. Let |global| be [=this=]'s [=relevant global object=]. 1. If |global|'s [=associated Document=] is not [=allowed to use=] the "[=run-ad-auction=]" [=policy-controlled feature=], then [=exception/throw=] a "{{NotAllowedError}}" {{DOMException}}. +1. Let |config| be the result of running [=parse and verify ad auction data config=] on |configIDL|. 1. Let |p| be [=a new promise=]. 1. Let |queue| be the result of [=starting a new parallel queue=]. 1. [=parallel queue/enqueue steps|Enqueue the following steps=] to |queue|: @@ -3134,6 +3174,9 @@ The getInterestGroupAdAuctionData(|config|) meth 1. [=list/For each=] |ig| of the [=user agent=]'s [=interest group set=]: 1. If |ig|'s [=interest group/ads=] is null or [=list/is empty=], [=iteration/continue=]. 1. Let |owner| be |ig|'s [=interest group/owner=]. + 1. If |config|'s [=auction data config/per buyer config=] [=map/is not empty=] and + |config|'s [=auction data config/per buyer config=][|owner|] does not + [=map/exist=], then [=iteration/continue=]. 1. If |igMap|[|owner|] does not [=map/exist=], then [=map/set=] |igMap|[|owner|] to a new [=list=]. 1. Let |ads| be a new [=list=]. 1. [=list/For each=] |ad| in |ig|'s [=interest group/ads=], [=list/append=] |ad|'s [=interest group ad/ad render ID=] to |ads|. @@ -3173,6 +3216,8 @@ The getInterestGroupAdAuctionData(|config|) meth :: |components| : [=server auction interest group/browser signals=] :: |browserSignals| + : [=server auction interest group/priority=] + :: |ig|'s [=interest group/priority=] 1. [=list/Append=] |serverIg| to |igMap|[|owner|]. 1. Let |result| be a new {{AdAuctionData}}. 1. Let |requestId| be the [=string representation=] of a [=version 4 UUID=]. @@ -3193,6 +3238,51 @@ The getInterestGroupAdAuctionData(|config|) meth
+
+ To parse and verify ad auction data config given an {{AdAuctionDataConfig}} |configIDL|: + + 1. Let |seller| be the result of running [=parse an https origin=] on + |configIDL|["{{AdAuctionDataConfig/seller}}"]. + 1. Let |coordinator| be the result of running [=parse an https origin=] on + |configIDL|["{{AdAuctionDataConfig/coordinatorOrigin}}"]. + 1. If |seller| or |coordinator| are failure, then [=exception/throw=] a {{TypeError}}. + 1. Let |config| be a new [=auction data config=] with the following [=struct/items=]: + : [=auction data config/seller=] + :: |seller| + : [=auction data config/coordinator=] + :: |coordinator| + : [=auction data config/request size=] + :: |configIDL|["{{AdAuctionDataConfig/requestSize}}"] if it [=map/exists=], null otherwise + : [=auction data config/per buyer config=] + :: The result of running [=parse per buyer auction data configs=] on + |configIDL|["{{AdAuctionDataConfig/perBuyerConfig}}"] + 1. If |config|'s [=auction data config/per buyer config=] [=map/is not empty=] + and |config|'s [=auction data config/request size=] is null: + 1. Let |requestSize| be 0. + 1. [=list/For each=] |buyerConfig| of |config|'s [=auction data config/per buyer config=]'s [=map/values=]: + 1. If |buyerConfig|'s [=auction data buyer config/size=] is null, + then [=exception/throw=] a {{TypeError}}. + 1. Set |requestSize| to |requestSize| + |buyerConfig|'s [=auction data buyer config/size=]. + 1. Set |config|'s [=auction data config/request size=] to |requestSize|. + 1. Return |config|. +
+ +
+ To parse per buyer auction data configs given an + {{AdAuctionDataBuyerConfig}} |perBuyerConfigIDL|: + 1. Let |configs| be a new [=ordered map=] whose [=map/keys=] are [=origins=] + and whose [=map/values=] are [=auction data configs=]. + 1. [=map/For each=] |buyerIDL| → |buyerConfigIDL| of |perBuyerConfigIDL|: + 1. Let |buyerConfig| be a new [=auction data buyer config=]. + 1. Set |buyerConfig|'s [=auction data buyer config/size=] to + |buyerConfigIDL|["{{AdAuctionDataBuyerConfig/targetSize}}"] if it + [=map/exists=], null otherwise. + 1. Let |buyer| be the result of running [=parse an https origin=] on |buyerIDL|. + 1. If |buyer| is failure, then [=exception/throw=] a {{TypeError}}. + 1. [=map/Set=] |configs|[|buyer|] to |buyerConfig|. + 1. Return |configs|. +
+ # Reporting # {#reporting} ## {{InterestGroupBiddingAndScoringScriptRunnerGlobalScope/forDebuggingOnly}} ## {#for-debugging-only-header} @@ -7520,6 +7610,31 @@ for a given [=k-anonymity key=]. These records are stored in the [=user agent=]. :: The [=moment=] when the k-anonymity status in this record was last fetched. +

auction data config

+ +An auction data config is a [=struct=] with the following [=struct/items=]: + +
+ : seller + :: An [=origin=]. + The origin of the seller running the ad auction. The [=origin/scheme=] must be "`https`". + : coordinator + :: The origin of the coordinator hosting public encryption keys for the server + running the ad auction. The [=origin/scheme=] must be "`https`". + : request size + :: {{unsigned long}} or null. An optional field, containing the desired size + for the returned encrypted request blob. + : per buyer config + :: A [=map=] whose [=map/keys=] are [=origins=] and [=map/values=] are [=auction data buyer config=]. +
+ +An auction data buyer config is a [=struct=] with the following [=struct/items=]: +
+ : size + :: {{unsigned long}} or null. An optional field, initially null, containing the + size of the request to allocate to this buyer. +
+ # Privacy Considerations # {#privacy-considerations} Protected Audience aims to advance the privacy of remarketing and custom audience