diff --git a/spec.bs b/spec.bs index 378967f..3e6694f 100644 --- a/spec.bs +++ b/spec.bs @@ -300,8 +300,7 @@ APIs exposing Private Aggregation {#apis-exposing-private-aggregation} This API is currently exposed in global scopes defined in the specifications of two APIs: 1. Shared Storage and -1. Protected Audience (via the - monkey patches below). +1. Protected Audience. Structures {#structures} ======================== @@ -1214,939 +1213,6 @@ Note: Without this, [=aggregatable reports=] would be subject to delays, making -Protected Audience API monkey patches {#protected-audience-api-monkey-patches} -============================================================================== - -Issue(43): This should be moved to the Protected Audience spec, along with any - other Protected Audience-specific details. - -New WebIDL {#protected-audience-api-specific-webidl} ----------------------------------------------------- - - -partial interface InterestGroupScriptRunnerGlobalScope { - readonly attribute PrivateAggregation privateAggregation; -}; - -dictionary PASignalValue { - required DOMString baseValue; - double scale; - (bigint or long) offset; -}; - -dictionary PAExtendedHistogramContribution { - required (PASignalValue or bigint) bucket; - required (PASignalValue or long) value; - bigint filteringId = 0; -}; - -[Exposed=InterestGroupScriptRunnerGlobalScope, SecureContext] -partial interface PrivateAggregation { - undefined contributeToHistogramOnEvent( - DOMString event, PAExtendedHistogramContribution contribution); -}; - -dictionary AuctionReportBuyersConfig { - required bigint bucket; - required double scale; -}; - -dictionary AuctionReportBuyerDebugModeConfig { - boolean enabled = false; - - // Must only be provided if `enabled` is true. - bigint? debugKey; -}; - -partial dictionary AuctionAdConfig { - sequence<bigint> auctionReportBuyerKeys; - record<DOMString, AuctionReportBuyersConfig> auctionReportBuyers; - AuctionReportBuyerDebugModeConfig auctionReportBuyerDebugModeConfig; -}; - - -Note: `requiredSellerCapabilities` is defined in the Protected - Audience spec. - -Issue: Do we want to align naming with implementation? - -The {{InterestGroupScriptRunnerGlobalScope/privateAggregation}} [=getter steps=] -are to [=get the privateAggregation=] given [=this=]. - -
-The contributeToHistogramOnEvent(DOMString -event, PAExtendedHistogramContribution contribution) method steps are: -1. Let |scopingDetails| be [=this=]'s [=PrivateAggregation/scoping details=]. -1. If |event| [=string/starts with=] "`reserved.`" and « "`reserved.always`", - "`reserved.loss`", "`reserved.win`" » does not [=list/contain=] |event|, - return. - - Note: No error is thrown to allow forward compatibility if additional - reserved event types are added later. -1. Let |bucket| be |contribution|["{{PAExtendedHistogramContribution/bucket}}"]. -1. If |bucket| is a {{PASignalValue}}: - 1. If |bucket|["{{PASignalValue/baseValue}}"] is not a valid [=signal base - value=], [=exception/throw=] a {{TypeError}}. - 1. If |bucket|["{{PASignalValue/offset}}"] is not a {{bigint}}, [=exception/ - throw=] a {{TypeError}}. -1. Otherwise, if |contribution|["{{PAExtendedHistogramContribution/bucket}}"] is - not [=set/contained=] in [=the exclusive range|the range=] 0 to - 2128, exclusive, [=exception/throw=] a {{TypeError}}. - - Issue: Make the error type consistent with - {{PrivateAggregation/contributeToHistogram(contribution)}}. -1. Let |value| be |contribution|["{{PAExtendedHistogramContribution/value}}"]. -1. If |value| is a {{PASignalValue}}: - 1. If |value|["{{PASignalValue/baseValue}}"] is not a valid [=signal base - value=], [=exception/throw=] a {{TypeError}}. - 1. If |value|["{{PASignalValue/offset}}"] is a {{bigint}}, [=exception/ - throw=] a {{TypeError}}. -1. Otherwise, if |contribution|["{{PAExtendedHistogramContribution/value}}"] is - negative, [=exception/throw=] a {{TypeError}}. -1. If |contribution|["{{PAExtendedHistogramContribution/filteringId}}"] is - not [=set/contained=] in [=the exclusive range|the range=] 0 to - 256[=default filtering ID max bytes=], exclusive, [=exception/ - throw=] a {{TypeError}}. - - Issue: Make the error types on validation issues here and above consistent - with {{PrivateAggregation/contributeToHistogram(contribution)}}. - - Note: It is not currently possible to set a non-default filtering ID max - bytes for Protected Audience. -1. Let |batchingScope| be null. -1. If |event| [=string/starts with=] "`reserved.`", set |batchingScope| to the - result of running |scopingDetails|' [=scoping details/get batching scope - steps=]. - - Note: Each non-reserved |event| will have a different [=batching scope=] - that is created later. -1. Let |entry| be a new [=on event contribution cache entry=] with the items: - : [=on event contribution cache entry/contribution=] - :: |contribution| - : [=on event contribution cache entry/batching scope=] - :: |batchingScope| - : [=on event contribution cache entry/debug scope=] - :: The result of running |scopingDetails|' [=scoping details/get debug scope - steps=]. - : [=on event contribution cache entry/worklet function=] - :: The [=worklet function=] that is currently being executed. - -1. Let |global| be [=this=]'s [=relevant global object=]. -1. Let |auctionConfig| be |global|'s - [=InterestGroupScriptRunnerGlobalScope/auction config=]. -1. Let |ig| be the result of [=maybe obtain an interest group|maybe obtaining an - interest group=] given |global|. -1. Let |cacheMap| be |auctionConfig|'s [=auction config/per-bid or seller on - event contribution cache=]. -1. If |cacheMap|[|ig|] does not [=map/exist=], [=map/set=] |cacheMap|[|ig|] to - a new [=on event contribution cache=]. -1. Let |onEventContributionCache| be |cacheMap|[|ig|]. -1. If |onEventContributionCache|[|event|] does not [=map/exist=], set - |onEventContributionCache|[|event|] to a new [=list=]. -1. [=list/Append=] |entry| to |onEventContributionCache|[|event|]. - -Issue: Ensure errors are of an appropriate type, e.g. {{InvalidAccessError}} is - deprecated. - -Issue(44): Consider accepting an array of contributions. - -
- -WebIDL modifications {#protected-audience-api-webidl-modifications} -------------------------------------------------------------------- - -The {{AuctionAdConfig}} and {{AuctionAdInterestGroup}} dictionaries are -modified to add a new field: - -dictionary ProtectedAudiencePrivateAggregationConfig { - USVString aggregationCoordinatorOrigin; -}; - -partial dictionary AuctionAdConfig { - ProtectedAudiencePrivateAggregationConfig privateAggregationConfig; -}; - -partial dictionary AuctionAdInterestGroup { - ProtectedAudiencePrivateAggregationConfig privateAggregationConfig; -}; - - -Note: `sellerCapabilities` is defined in the Protected - Audience spec - -Structures {#protected-audience-api-specific-structures} --------------------------------------------------------- - -

Extending auction config

- -Extend the auction config [=struct=] to add new fields: -
-: per-bid or seller on event contribution cache -:: A [=map=] from [=interest group=] or null to a [=on event contribution - cache=]. - - Note: a null key represents the seller. -: batching scope map -:: A [=map=] from a [=tuple=] consisting of an origin (an - [=origin=]) and a coordinator (an [=aggregation - coordinator=]) to a [=batching scope=]. - - Note: Does not include [=batching scopes=] for contributions conditional on - non-reserved events. -: permissions policy state -:: A [=permissions policy state=]. -: seller Private Aggregation coordinator -:: An [=aggregation coordinator=]. Defaults to the [=default aggregation - coordinator=]. -: auction report buyer keys -:: A [=map=] from buyer [=origins=] to {{bigint}}s. -: auction report buyers -:: A [=map=] from [=strings=] to {{AuctionReportBuyersConfig}}s. -: auction report buyer debug details -:: A [=debug details=]. - - Issue: Consider replacing the strings above with specific enum types. - -
- -

Extending interest group

- -Extend the interest group [=struct=] to add a new -field: -
-: Private Aggregation coordinator -:: An [=aggregation coordinator=] or null. - - Note: a null value specifies the default coordinator. - -
- -
-Add the following definitions in a new subsection at the end of -Structures, -renumbered appropriately. - -

Permissions policy state

-A permissions policy state is a [=struct=] with the following items: -
-: private aggregation enabled -:: A [=boolean=] (default false) - -
- -

Signal base value

-A signal base value is one of the following: -
-: "winning-bid" -:: The numeric value is the bid value of the winning bid. -: "highest-scoring-other-bid" -:: The numeric value is the bid value of the highest scoring bid that did not - win. -: "script-run-time" -:: The numeric value is the number of milliseconds of CPU time the calling - function (e.g. `generateBid()`) took to run. -: "signals-fetch-time" -:: The numeric value is the number of milliseconds it took for the trusted - bidding or scoring signals fetch to complete, when called from - `generateBid()` or `scoreAd()`, respectively. - - Issue: Can this value be used in `reportWin()` or `reportResult()`? -: "bid-reject-reason" -:: The numeric value is an integer representing the reason a bid was rejected. - - Note: this mapping to an integer is defined in [=determine a signal's - numeric value=]. - -
- -

Worklet function

-A worklet function is one of the following: -
-: "generate-bid" -:: The `generateBid()` function. -: "score-ad" -:: The `scoreAd()` function. -: "report-result" -:: The `reportResult()` function. -: "report-win" -:: The `reportWin()` function. - -
- -

On event contribution cache entry

-An on event contribution cache entry is a [=struct=] with the following items: -
-: contribution -:: A {{PAExtendedHistogramContribution}} -: batching scope -:: A [=batching scope=] or null -: debug scope -:: A [=debug scope=] -: debug details -:: A [=debug details=] or null (default null) -: worklet function -:: A [=worklet function=] - -
- -

On event contribution cache

-An on event contribution cache is a [=map=] from [=string=] to a [=list=] of -[=on event contribution cache entries=]. - -

Extending -InterestGroupScriptRunnerGlobalScope

- -Extend the global -scopes subsection to add: - -Each {{InterestGroupScriptRunnerGlobalScope}} has an: -
-: auction config -:: An auction config - -
- -

Extending -InterestGroupReportingScriptRunnerGlobalScope

- -Extend the InterestGroupReportingScriptRunnerGlobalScope -subsection to add an extra field to the end of the list beginning -"Each {{InterestGroupReportingScriptRunnerGlobalScope}} has a": -
-: interest group -:: Null or an [=interest group=]. Null for seller reporting - (i.e. `reportResult()`). - -
- -Algorithm modifications {#protected-audience-api-algorithm-modifications} -------------------------------------------------------------------------- - -The {{Navigator/joinAdInterestGroup()}} method steps are modified to add the -following steps at the end of the scope nested under step 5 ("Validate the given -group and ..."): -
-17. If |group|["{{AuctionAdInterestGroup/privateAggregationConfig}}"] - [=map/exists=]: - 1. Let |aggregationCoordinator| be the result of [=obtaining the coordinator - from a Private Aggregation config=] given - |group|["{{AuctionAdInterestGroup/privateAggregationConfig}}"]. - 1. If |aggregationCoordinator| is a {{DOMException}}, then - [=exception/throw=] |aggregationCoordinator|. - 1. Set interestGroup's [=interest group/Private - Aggregation coordinator=] to |aggregationCoordinator|. - -
- -The {{Navigator/runAdAuction()}} method steps are modified to add the -following step just after step 5 ("If auctionConfig is a -failure, then..."), renumbering the later steps as appropriate: -
-6. Set auctionConfig's [=auction config/permissions policy - state=] to a new [=permissions policy state=] with the items: - : [=permissions policy state/private aggregation enabled=] - :: The result of determining whether global's [=associated - Document=] is [=allowed to use=] the - "[=private-aggregation=]" [=policy-controlled feature=]. - -
- -The validate and convert auction ad config steps are -modified to add the following steps just before the last step ("Return -auctionConfig"), renumbering the later step as appropriate: -
-31. If |config|["{{AuctionAdConfig/auctionReportBuyerKeys}}"] [=map/exists=]: - 1. Let |interestGroupBuyers| be |auctionConfig|'s interest group buyers. - 1. If |interestGroupBuyers| is null, set |interestGroupBuyers| to a new - [=list=]. - 1. [=list/For each=] |index| of [=the exclusive range|the range=] 0 to - |config|["{{AuctionAdConfig/auctionReportBuyerKeys}}"]'s [=list/size=], - exclusive: - 1. Let |key| be - |config|["{{AuctionAdConfig/auctionReportBuyerKeys}}"][|index|]. - 1. If |key| is not [=set/contained=] in [=the exclusive range|the - range=] 0 to 2128, exclusive, [=exception/throw=] a - {{TypeError}}. - 1. If |index| is equal to or greater than |interestGroupBuyers|' [=list/ - size=], [=iteration/continue=]. - - Note: [=iteration/Continue=] is used (instead of [=iteration/ - break=]) to match validation logic for all given buyer keys. - 1. Let |origin| be |interestGroupBuyers|[|index|]. - 1. [=map/Set=] |auctionConfig|'s [=auction config/auction report buyer - keys=][|origin|] to |key|. - - Issue: Check behavior when an origin is repeated in - {{AuctionAdConfig/interestGroupBuyers}}. -1. If |config|["{{AuctionAdConfig/auctionReportBuyers}}"] [=map/exists=]: - 1. [=map/For each=] |reportType| → |reportBuyerConfig| of - |config|["{{AuctionAdConfig/auctionReportBuyers}}"]: - 1. If « "`interestGroupCount`", "`bidCount`", - "`totalGenerateBidLatency`", "`totalSignalsFetchLatency`" » does not - [=list/contain=] |reportType|, [=iteration/continue=]. - - Note: No error is thrown to allow forward compatibility if - additional report types are added later. - - Issue: Should these strings be dash delimited? - - 1. If |reportBuyerConfig|["{{AuctionReportBuyersConfig/bucket}}"] is not - [=set/contained=] in [=the exclusive range|the range=] 0 to - 2128, exclusive, [=exception/throw=] a {{TypeError}}. - - Issue: Consider validating the case where the bucket used (after - summing) is too large. Currently, the implementation appears to - overflow. See - protected-audience/1040. - 1. [=map/Set=] |auctionConfig|'s [=auction config/auction report - buyers=][|reportType|] to |reportBuyerConfig|. - -1. Set |auctionConfig|'s [=auction config/auction report buyer debug details=] - to a new [=debug details=]. -1. If |config|["{{AuctionAdConfig/auctionReportBuyerDebugModeConfig}}"] - [=map/exists=]: - 1. Let |debugModeConfig| be - |config|["{{AuctionAdConfig/auctionReportBuyerDebugModeConfig}}"]. - 1. Let |enabled| be - |debugModeConfig|["{{AuctionReportBuyerDebugModeConfig/enabled}}"]. - 1. Let |debugKey| be - |debugModeConfig|["{{AuctionReportBuyerDebugModeConfig/debugKey}}"]. - 1. If |debugKey| is not null: - 1. If |debugKey| is not [=set/contained=] in [=the exclusive range|the - range=] 0 to 264, exclusive, [=exception/throw=] a - {{TypeError}}. - 1. If |enabled| is false, [=exception/throw=] a {{TypeError}}. - 1. Set |auctionConfig|'s [=auction config/auction report buyer debug - details=] to a new [=debug details=] with the items: - : [=debug details/enabled=] - :: |enabled| - : [=debug details/key=] - :: |debugKey| -1. If |config|["{{AuctionAdConfig/privateAggregationConfig}}"] [=map/exists=]: - 1. Let |aggregationCoordinator| be the result of [=obtaining the coordinator - from a Private Aggregation config=] given - |config|["{{AuctionAdConfig/privateAggregationConfig}}"]. - 1. If |aggregationCoordinator| is a {{DOMException}}, return failure. - 1. Set auctionConfig's [=auction config/seller Private - Aggregation coordinator=] to |aggregationCoordinator|. - -Issue: Make all map indexing links (throughout the spec) where possible, i.e. - matching this section. - -
- -The generate and score bids algorithm is modified by -inserting the following step before each of the two "Return leadingBidInfo's -leading bid" steps (one in a -nested scope), renumbering this and later steps as necessary. -
-1. [=Process the Private Aggregation contributions for an auction=] given - auctionConfig and leadingBidInfo. - -
- -The evaluate a script steps are modified in two ways. -First, we add the following steps after step 11 ("If -evaluationStatus is an [=ECMAScript/abrupt completion=]..."), -renumbering later steps as appropriate: -
-12. Set |global|'s {{InterestGroupScriptRunnerGlobalScope/privateAggregation}}'s - [=PrivateAggregation/allowed to use=] to |auctionConfig|'s [=auction config/ - permissions policy state=]'s [=permissions policy state/private aggregation - enabled=]. -1. Let |debugScope| be a new [=debug scope=]. -1. Set |global|'s {{InterestGroupScriptRunnerGlobalScope/privateAggregation}}'s - [=PrivateAggregation/scoping details=] to a new [=scoping details=] with the - [=struct/items=]: - : [=scoping details/get batching scope steps=] - :: An algorithm that performs the following steps: - 1. Let |origin| be |realm|'s [=realm/settings object=]'s [=environment - settings object/origin=]. - 1. Let |ig| be the result of [=maybe obtain an interest group|maybe - obtaining an interest group=] given |realm|'s [=realm/global - object=]. - 1. Let |aggregationCoordinator| be null. - 1. If |ig| is not null, set |aggregationCoordinator| to |ig|'s - [=interest group/Private Aggregation coordinator=]. - 1. Otherwise, set |aggregationCoordinator| to |auctionConfig|'s - [=auction config/seller Private Aggregation coordinator=]. - 1. If |aggregationCoordinator| is null, set |aggregationCoordinator| to - the [=default aggregation coordinator=]. - 1. Return the result of running [=get or create a batching scope=] given - |origin|, |aggregationCoordinator| and |auctionConfig|. - : [=scoping details/get debug scope steps=] - :: An algorithm that returns |debugScope|. - -
- -Issue: Once - protected-audience/615 is resolved, align the above monkey patch with - how access to other functions is prevented in - {{InterestGroupScriptRunnerGlobalScope}}s until the script's initial - execution is complete. - -Second, in the nested scope of the last step, we insert a new step just after -the step labelled "Clean up after script", renumbering the later step as -appropriate: -
-2. Let |debugDetails| be the result of [=get a debug details=] given - |debugScope|. -1. Let |ig| be the result of [=maybe obtain an interest group|maybe obtaining an - interest group=] given global. -1. Let |onEventContributionCache| be auctionConfig's [=auction - config/per-bid or seller on event contribution cache=][|ig|]. -1. [=map/iterate|For each=] event → |entries| of - |onEventContributionCache|: - 1. [=list/iterate|For each=] |onEventEntry| of |entries|: - 1. If |onEventEntry|'s [=on event contribution cache entry/debug scope=] - is |debugScope|, set |onEventEntry|'s [=on event contribution cache - entry/debug details=] to |debugDetails|. -1. [=Mark a debug scope complete=] given |debugScope|. - -
- -The evaluate a bidding script steps are modified in the -following two ways. First, we add a new parameter auction -config |auctionConfig|. - -Note: This algorithm already takes an [=interest group=] parameter |ig|. - -Second, we add the following step after step 6 ("Set global's -interest -group to ig"), renumbering later steps as appropriate: -
-7. Set global's [=InterestGroupScriptRunnerGlobalScope/auction - config=] to auctionConfig. - -
- -The evaluate a scoring script steps are modified in the -following two ways. First, we add a new parameter auction -config |auctionConfig|. - -Second, we add the following step after step 1 ("Let |global| be a new -{{InterestGroupScoringScriptRunnerGlobalScope}}."), -renumbering the later step as appropriate: -
-2. Set global's [=InterestGroupScriptRunnerGlobalScope/auction - config=] to auctionConfig. - -
- -The evaluate a reporting script steps are modified in -the following two ways. First, we add two new parameters: an -auction config |auctionConfig| and an [=interest -group=] or null |ig|. - -Second, we add the following step after step 1 ("Let |global| be a new -{{InterestGroupReportingScriptRunnerGlobalScope}}."), -renumbering the later step as appropriate: -
-2. Set |global|'s [=InterestGroupScriptRunnerGlobalScope/auction config=] to - auctionConfig. -1. Set |global|'s [=InterestGroupReportingScriptRunnerGlobalScope/interest - group=] to ig. - -
- -Then, we modify the invocations of the above algorithms to plumb the new -parameters in: - -The generate potentially multiple bids algorithm is -modified to add a new auction config parameter -|auctionConfig|. Additionally, its last step is modified by adding the argument -|auctionConfig| to the invocation of evaluating a bidding -script. Further, the generate and score bids -algorithm is modified by adding the argument |auctionConfig| to both invocations -of generate potentially multiple bids. - -The score and rank a bid algorithm is modified by -adding the argument |auctionConfig| to the invocation of -evaluating a scoring script. - -The report result algorithm is modified by passing in -the arguments |auctionConfig| and null to the invocation of -evaluate a reporting script. - -The report win algorithm is modified by passing in -the arguments |auctionConfig| and winner's -interest group to the invocation of -evaluate a reporting script. - -The estimated size of an interest -group algorithm is modified to add the following line at the end of the sum: -
-16. The [=string/length=] of the [=serialization of an origin|serialization=] of - ig's [=interest group/Private Aggregation coordinator=] if - the field is not null. - -
- -The update interest groups -steps are modified to add the following case at the end of the "Switch on -key" step. -
-
-: "`privateAggregationConfig`" -:: - 1. If |value| is not a [=map=] whose [=map/keys=] are [=strings=], jump to - the step labeled Abort update. - 1. If |value|["`aggregationCoordinatorOrigin`"] [=map/exists=]: - 1. If |value|["`aggregationCoordinatorOrigin`"] is not a [=string=], - jump to the step labeled Abort update. - 1. Let |aggregationCoordinator| be the result of [=obtaining the Private - Aggregation coordinator=] given - |value|["`aggregationCoordinatorOrigin`"]. - 1. If |aggregationCoordinator| is a {{DOMException}}, jump to the step - labeled Abort update. - 1. Otherwise, set ig's [=interest group/Private - Aggregation coordinator=] to |aggregationCoordinator|. - -
- -
- -New algorithms {#protected-audience-api-specific-new-algorithms} ----------------------------------------------------------------- - -Add the following definitions: - -
-To process the Private Aggregation contributions for an auction given -an auction config |auctionConfig| and a -leading bid info |leadingBidInfo|: -1. Let |winnerOrigin| be null. -1. If |leadingBidInfo|'s leading - bid is not null, set |winnerOrigin| to |leadingBidInfo|'s - leading bid's - interest group's - owner. -1. [=map/iterate|For each=] |ig| → |onEventContributionCache| of - |auctionConfig|'s [=auction config/per-bid or seller on event contribution - cache=]: - 1. Let |origin| be null. - 1. If |ig| is null, set |origin| to |auctionConfig|'s - seller. - 1. Otherwise, set |origin| to |ig|'s - owner. - 1. [=map/iterate|For each=] |event| → |entries| of - |onEventContributionCache|: - 1. If |event| is "`reserved.win`" or does not [=string/start with=] - "`reserved.`": - 1. If |origin| is not |winnerOrigin|, return. - 1. If |event| is "`reserved.loss`" and |origin| is |winnerOrigin|, - return. - 1. [=list/iterate|For each=] |onEventEntry| of |entries|: - 1. Let |filledInContribution| be the result of [=filling in the - contribution=] given |onEventEntry|'s [=on event contribution - cache entry/contribution=] and |leadingBidInfo|. - - Issue: Once - - protected-audience/627 is resolved, align 'filling in' - logic with `forDebuggingOnly`. - 1. If |event| does not [=string/start with=] "`reserved.`": - 1. Store |event|, |filledInContribution|, |onEventEntry|'s [=on - event contribution cache entry/debug details=] in the - {{FencedFrameConfig}} as appropriate. - - Note: Each non-reserved |event| will have a different - [=batching scope=]. - - Issue: Once - - protected-audience/616 and any successors are - landed, align integration and fill in fenced frame's - report a private aggregation - event. - 1. [=iteration/Continue=]. - 1. Let |entry| be a new [=contribution cache entry=] with the items: - : [=contribution cache entry/contribution=] - :: |filledInContribution| - : [=contribution cache entry/batching scope=] - :: |onEventEntry|'s [=on event contribution cache entry/batching - scope=] - : [=contribution cache entry/debug scope=] - :: |onEventEntry|'s [=on event contribution cache entry/debug - scope=] - : [=contribution cache entry/debug details=] - :: |onEventEntry|'s [=on event contribution cache entry/debug - details=] - 1. [=Append an entry to the contribution cache|Append=] |entry| to - the [=contribution cache=]. -1. Let |sellerBatchingScope| be the result of [=get or create a batching - scope|getting or creating a batching scope=] given |auctionConfig|'s seller, |auctionConfig|'s - [=auction config/seller Private Aggregation coordinator=], and - |auctionConfig|. -1. Let |auctionReportBuyersDebugScope| be a new [=debug scope=]. -1. [=map/For each=] |reportType| → |reportBuyerConfig| of |auctionConfig|'s - [=auction config/auction report buyers=]: - 1. [=map/For each=] |buyerOrigin| → |buyerOffset| of |auctionConfig|'s - [=auction config/auction report buyer keys=]: - 1. Let |bucket| be the sum of |buyerOffset| and |reportBuyerConfig|'s - {{AuctionReportBuyersConfig/bucket}}. - - Issue: Handle overflow here or in validation. See - protected-audience/1040. - 1. Let |value| be the result (a {{double}}) of switching on - |reportType|: -
- : "`interestGroupCount`" - :: The number of interest groups in the [=user agent=]'s interest group set whose owner is - |buyerOrigin|. - : "`bidCount`" - :: The number of valid bids generated by interest groups whose owner is - |buyerOrigin|. - : "`totalGenerateBidLatency`" - :: The sum of execution time in milliseconds for all `generateBid()` - calls in the auction for interest groups whose owner is - |buyerOrigin|. - : "`totalSignalsFetchLatency`" - :: The total time spent fetching trusted buyer signals in - milliseconds, or 0 if the interest group didn't fetch any - trusted signals. - : None of the above values - :: [=Assert=]: false - - Note: This enum value is validated in validate and convert auction ad - config. - -
- - Issue: More formally spec the values here. - 1. Set |value| to the result of multiplying |reportBuyerConfig|'s - {{AuctionReportBuyersConfig/scale}} with |value|. - 1. Set |value| to the maximum of 0.0 and |value|. - 1. Set |value| to the result of converting |value| to an integer by - truncating its fractional part. - 1. Set |value| to the minimum of |value| and 231−1. - 1. Let |contribution| be a new {{PAHistogramContribution}} with the - items: - : {{PAHistogramContribution/bucket}} - :: |bucket| - : {{PAHistogramContribution/value}} - :: |value| - : {{PAHistogramContribution/filteringId}} - :: 0 - - Issue: Consider allowing the filtering ID to be set here. - 1. [=map/For each=] |ig| of the [=user agent=]'s - interest group set whose - owner is - |buyerOrigin|: - 1. If seller capabilities don't allow this reporting, [=iteration/ - continue=]. - - Issue: Align behavior with seller capabilities handling once - protected-audience/966 is resolved. - 1. Let |entry| be a new [=contribution cache entry=] with the items: - : [=contribution cache entry/contribution=] - :: |contribution| - : [=contribution cache entry/batching scope=] - :: |sellerBatchingScope| - : [=contribution cache entry/debug scope=] - :: |auctionReportBuyersDebugScope| - 1. [=Append an entry to the contribution cache|Append=] |entry| to - the [=contribution cache=]. -1. [=Mark a debug scope complete=] given |auctionReportBuyersDebugScope| and - |auctionConfig|'s [=auction config/auction report buyer debug details=]. -1. [=map/For each=] (|origin|, aggregationCoordinator) → - |batchingScope| of |auctionConfig|'s [=auction config/batching scope map=]: - 1. [=Process contributions for a batching scope=] given |batchingScope|, - |origin|, "protected-audience" and null. - -Issue: Verify interaction with component auctions. - -Issue: Use `[=map/For each=]` where possible. -
- -
-To get or create a batching scope given an [=origin=] |origin|, an -[=aggregation coordinator=] |aggregationCoordinator| and an auction config |auctionConfig|, perform the following -steps. They return a [=batching scope=]. -1. Let |batchingScopeMap| be |auctionConfig|'s [=auction config/batching scope - map=]. -1. Let |tuple| be (|origin|, |aggregationCoordinator|). -1. If |batchingScopeMap|[|tuple|] does not [=map/exist=]: - 1. Set |batchingScopeMap|[|tuple|] to a new [=batching scope=]. - 1. If |aggregationCoordinator| is not null, [=set the aggregation - coordinator for a batching scope=] given |aggregationCoordinator| and - |batchingScopeMap|[|tuple|]. -1. Return |batchingScopeMap|[|tuple|]. - -
- -
-To fill in the contribution given a -{{PAExtendedHistogramContribution}} |contribution| and a -leading bid info |leadingBidInfo|, perform the -following steps. They return a {{PAHistogramContribution}}. -1. Let |bucket| be |contribution|["{{PAExtendedHistogramContribution/bucket}}"]. -1. If |bucket| is a {{PASignalValue}}, set |bucket| to the result of [=filling - in the signal value=] given |bucket|, 2128−1 and |leadingBidInfo|. -1. Let |value| be |contribution|["{{PAExtendedHistogramContribution/value}}"]. -1. If |value| is a {{PASignalValue}}, set |value| to the result of [=filling in - the signal value=] given |value|, 231−1 and |leadingBidInfo|. -1. Let |filledInContribution| be a new {{PAHistogramContribution}} with the - items: - : {{PAHistogramContribution/bucket}} - :: |bucket| - : {{PAHistogramContribution/value}} - :: |value| - : {{PAHistogramContribution/filteringId}} - :: |contribution|["{{PAExtendedHistogramContribution/filteringId}}"] -1. Return |filledInContribution|. - -
- -
-To fill in the signal value given a {{PASignalValue}} |value|, an -integer |maxAllowed| and a leading bid info -|leadingBidInfo|, perform the following steps. They return an integer. -1. [=Assert=]: |value|["{{PASignalValue/baseValue}}"] is a valid [=signal base - value=]. -1. Let |returnValue| be the result of [=determining a signal's numeric value=] - given |value|["{{PASignalValue/baseValue}}"] and |leadingBidInfo|. -1. If |value|["{{PASignalValue/scale}}"] [=map/exists=], set |returnValue| to - the result of multiplying |value|["{{PASignalValue/scale}}"] with - |returnValue|. -1. Set |returnValue| to the result of converting |returnValue| to an integer by - truncating its fractional part. -1. If |value|["{{PASignalValue/offset}}"] [=map/exists=], set |returnValue| to - the result of adding |returnValue| to |value|["{{PASignalValue/offset}}"]. -1. Clamp |returnValue| to [=the inclusive range|the range=] 0 to |maxAllowed|, - inclusive, and return the result. - -
- -
-To determine a signal's numeric value given a [=signal base value=] -|signalBaseValue| and a leading bid info -|leadingBidInfo|, perform the following steps. They return a {{double}}. -1. If |signalBaseValue| is "[=signal base value/winning-bid=]": - 1. If |leadingBidInfo|'s leading - bid is null, return 0. - 1. Otherwise, return |leadingBidInfo|'s - leading bid's - bid. -1. If |signalBaseValue| is - "[=signal base value/highest-scoring-other-bid=]": - 1. If |leadingBidInfo|'s highest - scoring other bid is null, return 0. - 1. Otherwise, return |leadingBidInfo|'s - highest scoring other - bid's bid. -1. If |signalBaseValue| is "[=signal base value/script-run-time=]": - 1. Return the number of milliseconds of CPU time that the calling function - (e.g. `generateBid()`) took to run. -1. If |signalBaseValue| is - "[=signal base value/signals-fetch-time=]": - Switch on the associated [=worklet function=]: -
- : [=worklet function/generate-bid=] - :: Return the number of milliseconds it took for the trusted bidding signals - fetch to complete, or 0 if no fetch was made. - : [=worklet function/score-ad=] - :: Return the number of milliseconds it took for the trusted scoring signals - fetch to complete or 0 if no fetch was made. - : [=worklet function/report-result=] - : [=worklet function/report-win=] - :: Return 0. - -
- - Issue: Consider disallowing this in the latter two [=worklet functions=]. -1. If |signalBaseValue| is - "[=signal base value/bid-reject-reason=]": - 1. If the bid did not succeed purely because it didn't meet the required - k-anonymity threshold, return 8. - 1. Let |bidRejectReason| be "`not-available`". - 1. If the seller provided a reject reason, set |bidRejectReason| to that - value. - 1. If |bidRejectReason| is: -
- : "`not-available`" - :: Return 0. - : "`invalid-bid`" - :: Return 1. - : "`bid-below-auction-floor`" - :: Return 2. - : "`pending-approval-by-exchange`" - :: Return 3. - : "`disapproved-by-exchange`" - :: Return 4. - : "`blocked-by-publisher`" - :: Return 5. - : "`language-exclusions`" - :: Return 6. - : "`category-exclusions`" - :: Return 7. - : None of the above values - :: [=Assert=]: false - - Note: this enum value is validated in `scoreAd()`. - - Issue: Verify this once - - protected-audience/627 is resolved. - - Issue: Once protected-audience/594 - lands, update this mapping to align. - - Issue: Verify handling when the bid was not rejected. - -
- - Issue: Consider disallowing this from reportWin() and reportResult(). - -
- -
-To maybe obtain an interest group given an -{{InterestGroupScriptRunnerGlobalScope}} |global|, perform the following steps. -They return an [=interest group=] or null: -1. Switch on |global|'s type: -
- : {{InterestGroupBiddingScriptRunnerGlobalScope}} - :: Return |global|'s interest group. - : {{InterestGroupScoringScriptRunnerGlobalScope}} - :: Return null. - : {{InterestGroupReportingScriptRunnerGlobalScope}} - :: Return |global|'s [=InterestGroupReportingScriptRunnerGlobalScope/interest - group=]. - -
- -
- -
-To obtain the coordinator from a Private Aggregation config given a -{{ProtectedAudiencePrivateAggregationConfig}} |config|, perform the following -steps. They return an [=aggregation coordinator=], null or a {{DOMException}}. - -1. If |config|["{{ProtectedAudiencePrivateAggregationConfig/aggregationCoordinatorOrigin}}"] - does not [=map/exist=], return null. -1. Return the result of [=obtaining the Private Aggregation coordinator=] given - |config|["{{ProtectedAudiencePrivateAggregationConfig/aggregationCoordinatorOrigin}}"]. - -
- Privacy considerations {#privacy-considerations} ================================================