From 61665eb426d00aaca0868fac948feb8aa7616d60 Mon Sep 17 00:00:00 2001 From: brusshamilton Date: Fri, 20 Sep 2024 12:38:54 -0400 Subject: [PATCH] [spec] Add component auction support for Bidding and Auction Services (#1276) * Add basic response handling * Add multiseller support * Apply suggestions from code review Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com> * address comments * Don't set default valued fields with default value. Fill in some TODOs * Apply suggestions from code review Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com> * Address comments * s/Null:/null:/ * Apply suggestions from code review Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com> * Address comments * fix build * Address comments * Apply suggestions from code review Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com> * Some fields in both top-level and component server auctions. * Apply suggestions from code review Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com> * combine server auction response bid and bid currency * formatting --------- Co-authored-by: qingxinwu <6334674+qingxinwu@users.noreply.github.com> --- spec.bs | 147 +++++++++++++++++++++++++++++--------------------------- 1 file changed, 77 insertions(+), 70 deletions(-) diff --git a/spec.bs b/spec.bs index 893ea04ff..48cce048c 100644 --- a/spec.bs +++ b/spec.bs @@ -1669,11 +1669,15 @@ and a [=real time reporting contributions map=] |realTimeContributionsMap|: 1. Let |topLevelDirectFromSellerSignalsRetrieved| be false. 1. [=list/For each=] |component| in |auctionConfig|'s [=auction config/component auctions=], [=parallel queue/enqueue steps|enqueue the following steps=] to |queue|: - 1. Let |compWinnerInfo| be the result of running [=generate and score bids=] with |component|, - |auctionConfig|, |global|, |bidIgs|, |bidDebugReportInfoList|, and |realTimeContributionsMap|. - 1. If |compWinnerInfo| is failure, return failure. + 1. If |component|'s [=auction config/server response=] is not null: + 1. Let |compWinnerInfo| be the result of running [=parse and validate server response=] with |component|, + |auctionConfig|, |global|, |bidIgs|, and |bidDebugReportInfoList|. + 1. Otherwise: + 1. Let |compWinnerInfo| be the result of running [=generate and score bids=] with |component|, + |auctionConfig|, |global|, |bidIgs|, |bidDebugReportInfoList|, and |realTimeContributionsMap|. + 1. If |compWinnerInfo| is failure, abort these steps. 1. If [=recursively wait until configuration input promises resolve=] given |auctionConfig| returns - failure, return failure. + failure, abort these steps. 1. If |topLevelDirectFromSellerSignalsRetrieved| is false: 1. Let |topLevelDirectFromSellerSignals| be the result of running [=get direct from seller signals=] given |seller|, |auctionConfig|'s @@ -2772,10 +2776,6 @@ a [=list=] of [=interest groups=] |bidIgs|, and a [=list=] of [=bid debug report |bidDebugReportInfoList|: 1. [=Assert=] that these steps are running [=in parallel=]. -1. [=Assert=] that |topLevelAuctionConfig| is null. - - Issue: TODO: Support multi-level auctions. - (WICG/turtledove#1254) 1. Let |requestId| be the value of |auctionConfig|'s [=auction config/server response id=]. 1. Let |requestContexts| be the value of |global|'s [=associated Document's=] [=node navigable's=] [=traversable navigable's=] [=traversable navigable/saved Bidding and Auction request context=]. @@ -2789,10 +2789,11 @@ a [=list=] of [=interest groups=] |bidIgs|, and a [=list=] of [=bid debug report (WICG/turtledove#1254) 1. If |response| is failure, then return failure. 1. If |response|'s [=server auction response/is chaff=] is true, return failure. -1. If |response|'s [=server auction response/top level seller=] is not null, return failure. - - Issue: TODO: Handle Bidding and Auction Services as component auctions. - (WICG/turtledove#1254) +1. If |response|'s [=server auction response/top level seller=] is not null: + 1. If |topLevelAuctionConfig| is null return failure. + 1. If |topLevelAuctionConfig|'s [=auction config/seller=] is not equal to + |response|'s [=server auction response/top level seller=], return failure. +1. Otherwise if |topLevelAuctionConfig| is not null, return failure. 1. Let |winningGroup| be the [=interest group=] in the [=user agent=]'s [=interest group set=] whose [=interest group/owner=] is |response|'s [=server auction response/interest group owner=] and [=interest group/name=] is |response|'s [=server auction response/interest group name=]. Return failure if none found. @@ -2802,30 +2803,30 @@ a [=list=] of [=interest groups=] |bidIgs|, and a [=list=] of [=bid debug report 1. If |response|'s [=server auction response/ad render url=] is |ad|'s [=interest group ad/render url=], then set |winningAd| to |ad|, and [=iteration/break=]. 1. If |winningAd| is null, then return failure. -1. Let |winningAdComponents| be a new [=list=] of [=interest group ads=]. + + Issue: TODO: Check that the buyerReportingId and buyerAndSellerReportingId from the + server response match that in the |winningAd|. + (WICG/turtledove#1254) +1. Let |winningAdDescriptor| be a new [=ad descriptor=] whose [=ad descriptor/url=] is + |response|'s [=server auction response/ad render url=]. +1. Let |winningAdComponents| be a new [=list=] of [=ad descriptors=]. 1. [=list/For each=] |componentAd| in |response|'s [=server auction response/ad components=]: 1. Let |ad| be the [=interest group ad=] from |winningGroup|'s [=interest group/ad components=] where the [=interest group ad/render url=] equals |componentAd|. If there is no matching element, return failure. - 1. [=list/Append=] |ad| to |winningAdComponents|. + 1. [=list/Append=] a new [=ad descriptor=] whose [=ad descriptor/url=] is + |componentAd| to |winningAdComponents|. 1. Let |winningBid| be a new [=generated bid=] with the following [=struct/items=]: - : [=generated bid/id=] - :: (0, 0) - : [=generated bid/for k-anon auction=] - :: TODO - : [=generated bid/bid=] - :: A new [=bid with currency=] with the following [=struct/items=]: - : [=bid with currency/value=] - :: |response|'s [=server auction response/bid=] - : [=bid with currency/currency=] - :: |response|'s [=server auction response/bid currency=] - - : [=generated bid/bid in seller currency=] + : [=generated bid/id=] :: TODO + : [=generated bid/bid=] + :: |response|'s [=server auction response/bid=] + : [=generated bid/bid in seller currency=] + :: Null : [=generated bid/ad=] - :: |response|'s [=server auction response/ad render url=] + :: |response|'s [=server auction response/ad metadata=] : [=generated bid/ad descriptor=] - :: |winningAd| + :: |winningAdDescriptor| : [=generated bid/ad component descriptors=] :: |winningAdComponents| : [=generated bid/ad cost=] @@ -2837,7 +2838,7 @@ a [=list=] of [=interest groups=] |bidIgs|, and a [=list=] of [=bid debug report : [=generated bid/bid ad=] :: |winningAd| : [=generated bid/modified bid=] - :: Null + :: Null if |topLevelAuctionConfig| is null, otherwise |response|'s [=server auction response/bid=] : [=generated bid/bid duration=] :: 0 : [=generated bid/component seller=] @@ -2861,40 +2862,35 @@ a [=list=] of [=interest groups=] |bidIgs|, and a [=list=] of [=bid debug report :: The value of |response|'s [=server auction response/component seller reporting=]'s [=server auction reporting info/reporting url=]. : [=reporting result/reporting beacon map=] :: The value of |response|'s [=server auction response/component seller reporting=]'s [=server auction reporting info/beacon urls=]. - +1. Let |topScore| be 0.0 if |response|'s [=server auction response/score=] is null, + |response|'s [=server auction response/score=] otherwise. 1. Let |winningBidInfo| be a new [=leading bid info=] with the following [=struct/items=]: : [=leading bid info/top score=] - :: |response|'s [=server auction response/score=]. + :: |topScore| : [=leading bid info/top non-k-anon-enforced score=] - :: TODO + :: |topScore| : [=leading bid info/top bids count=] - :: TODO + :: 1 : [=leading bid info/top non-k-anon-enforced bids count=] - :: TODO - : [=leading bid info/at most one top bid owner=] - :: TODO + :: 1 : [=leading bid info/leading bid=] :: |winningBid| : [=leading bid info/leading non-k-anon-enforced bid=] - :: TODO + :: |winningBid| : [=leading bid info/auction config=] :: |auctionConfig| - : [=leading bid info/second highest score=] - :: TODO - : [=leading bid info/highest scoring other bids count=] - :: TODO : [=leading bid info/highest scoring other bid=] - :: TODO - : [=leading bid info/highest scoring other bid owner=] - :: TODO + :: Null : [=leading bid info/top level seller=] - :: TODO + :: Null if |topLevelAuctionConfig| is null, otherwise |topLevelAuctionConfig|'s [=auction config/seller=]. : [=leading bid info/top level seller signals=] - :: TODO + :: Null : [=leading bid info/component seller=] - :: TODO + :: Null if |topLevelAuctionConfig| is null, otherwise |auctionConfig|'s [=auction config/seller=]. + : [=leading bid info/bidding data version=] + :: Null : [=leading bid info/scoring data version=] - :: TODO + :: Null : [=leading bid info/buyer reporting result=] :: |buyerReportingResult| : [=leading bid info/seller reporting result=] @@ -3049,45 +3045,55 @@ A server auction request context is a [=struct=] with the following [ (WICG/turtledove#1254) -A server auction response is a [=struct=] with the following [=struct/items=]: +A server auction response is a [=struct=] that contains auction result +from an auction executed on the trusted auction server. It has the following [=struct/items=]: +
: is chaff :: A [=boolean=] field indicating whether this response should be ignored. : ad render url - :: The [=URL=] of the ad for the winning bid. + :: [=URL=]. The [=leading bid info/leading bid=]'s [=generated bid/ad descriptor=]'s [=ad descriptor/url=] from the + auction. : ad components - :: A [=list=] of [=URLs=] containing the ad components for the winning bid. + :: A [=list=] of [=URLs=]. A list of winning bid's + [=generated bid/ad component descriptors=]'s [=ad descriptor/urls=] from the + auction. : interest group name - :: The winning interest group's name as a [=string=]. + :: A [=string=]. The winning bid's interest group [=interest group/name=]. : interest group owner - :: The winning interest group's owner [=origin=]. + :: An [=origin=]. The winning bid's interest group [=interest group/owner=]. : bidding groups - :: A [=list=] of interest group owner and interest group name pairs that bid - in this auction. + :: A [=list=] of interest group [=interest group/owner=] and + interest group [=interest group/name=] pairs that bid + in the auction. : score - :: {{double}} or Null. TODO + :: Null or {{double}}. Null if the server auction is not a component auction, + otherwise the {{ScoreAdOutput/desirability}} of component auction's winning bid. : bid - :: {{double}} or Null. TODO. - : bid currency - :: [=currency tag=] or Null. TODO. + :: Null or [=bid with currency=]. Null when the server auction is not a component auction. + For component auctions, contains the winning bid's [=generated bid/modified bid=] + when not null, otherwise the winning bid's [=generated bid/bid=]. : top level seller - :: An [=origin=] or Null. Null when the server response is not feeding into an - on-device auction. Otherwise the value is the expected top-level seller for - that auction. - : ad metadata - :: A JSON [=string=]. TODO + :: Null or an [=origin=]. Null when the server auction is not a component auction. + Otherwise the value is the expected top-level seller [=origin=] for + that auction. This should match the [=auction config/seller=] for the top-level [=auction config=]. + : ad metadata + :: Null or a JSON [=string=]. Null when the server auction is not a component auction. + Otherwise the value contains the component auction's winning bid's [=generated bid/ad=]. : buyer reporting id :: TODO. : buyer and seller reporting id :: TODO. : error - :: TODO. + :: Null or [=string=]. When not null, contains an error message from the + auction executed on the trusted auction server. May be used to provide + additional context for the result of an auction. : buyer reporting - :: [=server auction reporting info=] + :: [=Server auction reporting info=] : top level seller reporting - :: [=server auction reporting info=] or Null. + :: Null or [=server auction reporting info=]. : component seller reporting - :: [=server auction reporting info=] or Null. + :: Null or [=server auction reporting info=].
A server auction reporting info is a [=struct=] with the following [=struct/items=]: @@ -7028,8 +7034,9 @@ result of [=evaluating a bidding script=], or an [=additional bid=] provided by :: A [=boolean=], initially true. If this is false, the bid is only used to determine the hypothetical winner with no k-anonymity constraints, which would be used to [=update k-anonymity counts=] only. : bid - :: A [=bid with currency=]. If the [=bid with currency/value=] is zero or negative, then this - [=interest group=] will not participate in the auction. + :: A [=bid with currency=], or null. If not null and the [=bid with currency/value=] is zero or negative, then this + [=interest group=] will not participate in the auction. This field should only + be null if the top-level auction is performed on a trusted auction server. : bid in seller currency :: A {{double}} or null. An equivalent of the original bid in seller's currency. This is either the original bid if the currency already matched, or a conversion provided by `scoreAd()`.