Protected Audience (formerly FLEDGE)

Draft Community Group Report,

This version:
https://wicg.github.io/turtledove/
Editor:
(Google)
Participate:
GitHub WICG/turtledove (new issue, open issues)
Commits:
GitHub spec.bs commits

Abstract

Provides a privacy advancing API to facilitate interest group based advertising.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

This section is non-normative.

The Protected Audience API facilitates selecting an advertisement to display to a user based on a previous interaction with the advertiser or advertising network.

When a user’s interactions with an advertiser indicate an interest in something, the advertiser can ask the browser to record this interest on-device by calling navigator.joinAdInterestGroup(). Later, when a website wants to select an advertisement to show to the user, the website can call navigator.runAdAuction() to ask the browser to conduct an auction where each of these on-device recorded interests are given the chance to calculate a bid to display their advertisement.

2. Joining Interest Groups

This first introductory paragraph is non-normative.

When a user’s interactions with a website indicate that the user may have a particular interest, an advertiser or someone working on behalf of the advertiser (e.g. a demand side platform, DSP) can ask the user’s browser to record this interest on-device by calling navigator.joinAdInterestGroup(). This indicates an intent to display an advertisement relevant to this interest to this user in the future. The user agent has an interest group set, a list of interest groups in which owner / name pairs are unique.

2.1. joinAdInterestGroup()

[SecureContext]
partial interface Navigator {
  Promise<undefined> joinAdInterestGroup(AuctionAdInterestGroup group);
};

dictionary AuctionAd {
  required USVString renderURL;
  any metadata;

  USVString buyerReportingId;
  USVString buyerAndSellerReportingId;
  sequence<USVString> allowedReportingOrigins;
};

dictionary GenerateBidInterestGroup {
  required USVString owner;
  required USVString name;
  required double lifetimeMs;

  boolean enableBiddingSignalsPrioritization = false;
  record<DOMString, double> priorityVector;

  record<USVString, sequence<DOMString>> sellerCapabilities;
  DOMString executionMode = "compatibility";
  USVString biddingLogicURL;
  USVString biddingWasmHelperURL;
  USVString updateURL;
  USVString trustedBiddingSignalsURL;
  sequence<USVString> trustedBiddingSignalsKeys;
  DOMString trustedBiddingSignalsSlotSizeMode = "none";
  long maxTrustedBiddingSignalsURLLength;
  any userBiddingSignals;
  sequence<AuctionAd> ads;
  sequence<AuctionAd> adComponents;
};

dictionary AuctionAdInterestGroup : GenerateBidInterestGroup {
  double priority = 0.0;
  record<DOMString, double> prioritySignalsOverrides;
  DOMString additionalBidKey;
};

AuctionAdInterestGroup is used by navigator.joinAdInterestGroup(), and when an interest group is stored to interest group set. priority and prioritySignalsOverrides are not passed to generateBid() because they can be modified by generatedBid() calls, so could theoretically be used to create a cross-site profile of a user accessible to generateBid() methods, otherwise.

The joinAdInterestGroup(group) method steps are:

Temporarily, Chromium does not include the required keyword for lifetimeMs, and instead starts this algorithm with the step

  1. If group["lifetimeMs"] does not exist, throw a TypeError.

This is detectable because it can change the set of fields that are read from the argument when a TypeError is eventually thrown, but it will never change whether the call succeeds or fails.

  1. Let global be this's relevant global object.

  2. If global’s associated Document is not allowed to use the "join-ad-interest-group" policy-controlled feature, then throw a "NotAllowedError" DOMException.

  3. Let frameOrigin be this's relevant settings object's origin.

  4. Assert that frameOrigin is not an opaque origin and its scheme is "https".

  5. Let interestGroup be a new interest group.

  6. Validate the given group and set interestGroup’s fields accordingly.

    1. Set interestGroup’s expiry to the current wall time plus group["lifetimeMs"] milliseconds.

    2. Set interestGroup’s next update after to the current wall time plus 24 hours.

    3. Set interestGroup’s owner to the result of parsing an https origin on group["owner"].

    4. If interestGroup’s owner is failure, then throw a TypeError.

    5. Optionally, throw a "NotAllowedError" DOMException.

      Note: This implementation-defined condition is intended to allow user agents to decline for a number of reasons, for example the owner's site not being enrolled.

    6. Set interestGroup’s name to group["name"].

    7. Set interestGroup’s priority to group["priority"].

    8. Set interestGroup’s enable bidding signals prioritization to group["enableBiddingSignalsPrioritization"].

    9. If group["priorityVector"] exists, then set interestGroup’s priority vector to group["priorityVector"].

    10. If group["prioritySignalsOverrides"] exists, then set interestGroup’s priority signals overrides to group["prioritySignalsOverrides"].

    11. If group["sellerCapabilities"] exists, for each sellerStringcapabilities of group["sellerCapabilities"]:

      1. Let sellerCapabilities be a new set of seller capabilities.

      2. For each capabilityString of capabilities:

        1. If capabilityString is "interest-group-counts" or "latency-stats", then append capabilityString to sellerCapabilities.

          Note: For forward compatibility with new values, don’t throw.

      3. If sellerString is "*", then set interestGroup’s all sellers capabilities to sellerCapabilities.

      4. Otherwise:

        1. If interestGroup’s seller capabilities is null, then set interestGroup’s seller capabilities to a new ordered map whose keys are origins and whose values are sets of seller capabilities.

        2. Let sellerUrl be the result of running the URL parser on sellerString.

        3. If sellerUrl is not failure:

          1. Let seller be sellerUrl’s origin.

          2. If interestGroup’s seller capabilities does not contain seller, then set interestGroup’s seller capabilities[seller] to sellerCapabilities.

    12. If group["executionMode"] is "compatibility", "frozen-context", or "group-by-origin", then set interestGroup’s execution mode to it.

    13. For each groupMember and interestGroupField in the following table

      Group member Interest group field
      "biddingLogicURL" bidding url
      "biddingWasmHelperURL" bidding wasm helper url
      "updateURL" update url
      "trustedBiddingSignalsURL" trusted bidding signals url
      1. If group contains groupMember:

        1. Let parsedUrl be the result of running the URL parser on group[groupMember].

        2. Throw a TypeError if any of the following conditions hold:

        3. Set interestGroup’s interestGroupField to parsedUrl.

    14. If interestGroup’s trusted bidding signals url's query is not null, then throw a TypeError.

    15. If group["trustedBiddingSignalsKeys"] exists, then set interestGroup’s trusted bidding signals keys to group["trustedBiddingSignalsKeys"].

    16. If group["maxTrustedBiddingSignalsURLLength"] exists:

      1. If group["maxTrustedBiddingSignalsURLLength"] ≥ 0, set interestGroup’s max trusted bidding signals url length to group["maxTrustedBiddingSignalsURLLength"], otherwise throw a TypeError.

    17. If group["userBiddingSignals"] exists:

      1. Set interestGroup’s user bidding signals to the result of serializing a JavaScript value to a JSON string, given group["userBiddingSignals"]. This can throw a TypeError.

    18. If group["trustedBiddingSignalsSlotSizeMode"] is one of "none", "slot-size", or "all-slots-requested-sizes", set interestGroup’s trusted bidding signals slot size mode to group["trustedBiddingSignalsSlotSizeMode"].

    19. For each groupMember and interestGroupField in the following table

      Group member Interest group field
      "ads" ads
      "adComponents" ad components
      1. If group contains groupMember, for each ad of group[groupMember]:

        1. Let igAd be a new interest group ad.

        2. Let renderURL be the result of running the URL parser on ad["renderURL"].

        3. Throw a TypeError if any of the following conditions hold:

        4. Set igAd’s render url to renderURL.

        5. If ad["metadata"] exists, then let igAd’s metadata be the result of serializing a JavaScript value to a JSON string, given ad["metadata"]. This can throw a TypeError.

        6. If groupMember is "ads":

          1. If ad["buyerReportingId"] exists, then set igAd’s buyer reporting ID to it.

          2. If ad["buyerAndSellerReportingId"] exists, then set igAd’s buyer and seller reporting ID to it.

          3. If ad["allowedReportingOrigins"] exists:

            1. Let allowedReportingOrigins be a new list of origins.

            2. For each originStr in ad["allowedReportingOrigins"]:

              1. Let origin be the result of parsing an https origin on originStr.

              2. If origin is failure, then throw a TypeError.

              3. Append origin to allowedReportingOrigins.

              4. If allowedReportingOrigins’s size > 10, throw a TypeError.

            3. Set igAd’s allowed reporting origins to allowedReportingOrigins.

        7. Append igAd to interestGroup’s interestGroupField.

    20. If group["additionalBidKey"] exists:

      1. Let decodedKey be the result of running forgiving-base64 decode with group["additionalBidKey"].

      2. Throw a TypeError if any of the following conditions hold:

      3. Set interestGroup’s additional bid key to decodedKey.

  7. If interestGroup’s estimated size > 1048576, then throw a TypeError.

  8. Let p be a new promise.

  9. Let queue be the result of starting a new parallel queue.

  10. Enqueue the following steps to queue:

    1. Let permission be the result of checking interest group permissions with interestGroup’s owner, frameOrigin, and "join".

    2. If permission is false, then queue a global task on DOM manipulation task source, given global, to reject p with a "NotAllowedError" DOMException and abort these steps.

    3. Queue a global task on DOM manipulation task source, given global, to resolve p with undefined.

    4. If the browser is currently storing an interest group with owner and name that matches interestGroup, then set the bid counts, join counts, and previous wins of interestGroup to the values of the currently stored one and remove the currently stored one from the browser.

    5. Set interestGroup’s joining origin to this's relevant settings object's top-level origin.

    6. Set interestGroup’s join time to the current wall time.

    7. If the most recent entry in interestGroup’s join counts corresponds to the current day in UTC, increment its count. If not, insert a new tuple the time set to the current UTC day and a count of 1.

    8. Store interestGroup in the user agent's interest group set.

  11. Return p.

2.2. Interest Group Storage Maintenance

There is a job that periodically performs storage maintenance on the user agent's interest group set. It performs operations such as removing expired or excess interest groups. An interest group set must respect the following limits. Implementations may define their own values for the below constants, however we supply the below values as a starting point, inspired by what the initial implementation of this specification uses:

To perform storage maintenance:
  1. Let ownersAndExpiry be a new ordered map whose keys are origins and values are moments.

    Note: The key is from owner, and value is from expiry. It’s used to determine a set of owners whose interest groups will be removed from the user agent's interest group set because the number of distinct owners exceeds the Interest group set max owners limit. It’s sorted based on their values (expiry) in descending order, in order to remove interest groups of owners expiring soonest first.

  2. Let now be the current wall time.

  3. For each ig of the user agent's interest group set:

    1. Let owner be ig’s owner.

    2. If ig’s expiry is before now, then remove ig from the user agent's interest group set and continue.

    3. If ownersAndExpiry[owner] exists, then set ownersAndExpiry[owner] to ig’s expiry if it comes after ownersAndExpiry[owner].

    4. Otherwise, set ownersAndExpiry[owner] to ig’s expiry.

  4. If ownersAndExpiry’s size > interest group set max owners, then set ownersAndExpiry to ownersAndExpiry sorted in descending order with a being less than b if a’s value comes before b’s value, where values are expiry.

  5. Let owners be the keys of ownersAndExpiry.

  6. For each i in the range from 0 to owners’s size, exclusive:

    1. If iinterest group set max owners, then remove interest groups from the user agent's interest group set whose owner is owners[i], and continue.

    2. Let regularIgs be a list of regular interest groups in the user agent's interest group set whose owner is owners[i].

    3. If regularIgs’s size > max regular interest groups per owner, then clear excess interest groups with regularIgs and max regular interest groups per owner.

    4. Let negativeIgs be a list of negative interest groups in the user agent's interest group set whose owner is owners[i].

    5. If negativeIgs’s size > max negative interest groups per owner, then clear excess interest groups with negativeIgs and max negative interest groups per owner.

  7. For each owner of owners:

    1. Let igs be a list of interest groups in the user agent's interest group set whose owner is owner, sorted in descending order with a being less than b if aexpiry comes before bexpiry.

    2. Let cumulativeSize be 0.

    3. For each ig of igs:

      1. If the sum of cumulativeSize and ig’s estimated size > max interest groups total size per owner, then remove ig from the user agent's interest group set.

      2. Otherwise, increment cumulativeSize by ig’s estimated size.

To clear excess interest groups with a list of interest groups igs, and an integer maxIgs:
  1. Let sortedIgs be igs sorted in descending order with a being less than b if a’s expiry comes before b’s expiry.

    Note: In order to remove interest groups expiring soonest first, sort interest groups based on their expiry in descending order.

  2. For each i in the range from maxIgs to igs’s size, exclusive:

    1. Remove sortedIgs[i] from the user agent's interest group set.

3. Leaving Interest Groups

3.1. leaveAdInterestGroup()

This first introductory paragraph is non-normative.

navigator.leaveAdInterestGroup() removes a user from a particular interest group.

[SecureContext]
partial interface Navigator {
  Promise<undefined> leaveAdInterestGroup(optional AuctionAdInterestGroupKey group = {});
};

dictionary AuctionAdInterestGroupKey {
  required USVString owner;
  required USVString name;
};

The leaveAdInterestGroup(group) method steps are:

  1. Let global be this's relevant global object.

  2. Let frameOrigin be global’s origin.

  3. Assert that frameOrigin is not an opaque origin and its scheme is "https".

  4. Let p be a new promise.

  5. If group is empty:

    1. Let instance be global’s browsing context's fenced frame config instance.

    2. If instance is null, then return.

    3. Let interestGroup be instance’s interest group descriptor.

    4. Run these steps in parallel:

      1. Queue a global task on DOM manipulation task source, given global, to resolve p with undefined.

      2. If interestGroup is not null:

        1. Let owner be interestGroup’s owner.

        2. If owner is same origin with frameOrigin, then remove interest groups from the user agent's interest group set whose owner is owner and name is interestGroup’s name.

  6. Otherwise:

    1. If global’s associated Document is not allowed to use the "join-ad-interest-group" policy-controlled feature, then throw a "NotAllowedError" DOMException.

      Note: Both joining and leaving interest groups use the "join-ad-interest-group" feature.

    2. Let owner be the result of parsing an https origin with group["owner"].

    3. If owner is failure, throw a TypeError.

    4. Run these steps in parallel:

      1. Let permission be the result of checking interest group permissions with owner, frameOrigin, and "leave".

      2. If permission is false, then queue a global task on DOM manipulation task source, given global, to reject p with a "NotAllowedError" DOMException and abort these steps.

      3. Queue a global task on DOM manipulation task source, given global, to resolve p with undefined.

      4. Remove interest groups from the user agent's interest group set whose owner is owner and name is group["name"].

  7. Return p.

3.2. clearOriginJoinedAdInterestGroups()

This first introductory paragraph is non-normative.

navigator.clearOriginJoinedAdInterestGroups() removes a user from interest groups whose joining origin is the associated Navigator's relevant settings object's top-level origin.

[SecureContext]
partial interface Navigator {
  Promise<undefined> clearOriginJoinedAdInterestGroups(
      USVString owner, optional sequence<USVString> interestGroupsToKeep = []);
};

The clearOriginJoinedAdInterestGroups(owner, interestGroupsToKeep) method steps are:

  1. Let frameOrigin be this's relevant settings object's origin.

  2. Assert that frameOrigin is not an opaque origin and its scheme is "https".

  3. Let p be a new promise.

  4. Let global be this's relevant global object.

  5. If global’s associated Document is not allowed to use the "join-ad-interest-group" policy-controlled feature, then throw a "NotAllowedError" DOMException.

    Note: Both joining and leaving interest groups use the "join-ad-interest-group" feature.

  6. Let ownerOrigin be the result of parsing an https origin with owner.

  7. If ownerOrigin is failure, throw a TypeError.

  8. Run these steps in parallel:

    1. Let permission be the result of checking interest group permissions with ownerOrigin, frameOrigin, and "leave".

    2. If permission is false, then queue a global task on the DOM manipulation task source given global, reject p with a "NotAllowedError" DOMException and abort these steps.

    3. Queue a global task on the DOM manipulation task source given global, to resolve p with undefined.

    4. Remove interest groups from the user agent's interest group set whose owner is ownerOrigin, whose joining origin is frameOrigin, and whose name is not in interestGroupsToKeep.

  9. Return p.

4. Running Ad Auctions

This first introductory paragraph is non-normative.

When a website or someone working on behalf of the website (e.g. a supply side platform, SSP) wants to conduct an auction to select an advertisement to display to the user, they can call the navigator.runAdAuction() function, providing an auction configuration that tells the browser how to conduct the auction and which on-device recorded interests are allowed to bid in the auction for the chance to display their advertisement.

4.1. runAdAuction()

[SecureContext]
partial interface Navigator {
  Promise<(USVString or FencedFrameConfig)?> runAdAuction(AuctionAdConfig config);
};

dictionary AuctionAdConfig {
  required USVString seller;
  required USVString decisionLogicURL;

  USVString trustedScoringSignalsURL;
  long maxTrustedScoringSignalsURLLength;
  sequence<USVString> interestGroupBuyers;
  Promise<any> auctionSignals;
  Promise<any> sellerSignals;
  Promise<DOMString> directFromSellerSignalsHeaderAdSlot;
  Promise<record<USVString, USVString>> deprecatedRenderURLReplacements;
  unsigned long long sellerTimeout;
  unsigned short sellerExperimentGroupId;
  Promise<record<USVString, any>> perBuyerSignals;
  Promise<record<USVString, unsigned long long>> perBuyerTimeouts;
  Promise<record<USVString, unsigned long long>> perBuyerCumulativeTimeouts;
  unsigned long long reportingTimeout;
  USVString sellerCurrency;
  Promise<record<USVString, USVString>> perBuyerCurrencies;
  record<USVString, unsigned short> perBuyerGroupLimits;
  record<USVString, unsigned short> perBuyerExperimentGroupIds;
  record<USVString, record<USVString, double>> perBuyerPrioritySignals;
  sequence<DOMString> requiredSellerCapabilities;
  record<DOMString, DOMString> requestedSize;
  sequence<record<DOMString, DOMString>> allSlotsRequestedSizes;
  Promise<undefined> additionalBids;
  DOMString auctionNonce;
  sequence<AuctionAdConfig> componentAuctions = [];
  AbortSignal? signal;
  Promise<boolean> resolveToConfig;
};

The runAdAuction(config) method steps are:

  1. Let global be this's relevant global object.

  2. Let settings be this's relevant settings object.

  3. If global’s associated Document is not allowed to use the "run-ad-auction" policy-controlled feature, then throw a "NotAllowedError" DOMException.

  4. Let auctionConfig be the result of running validate and convert auction ad config with config and true.

  5. If auctionConfig is failure, then throw a TypeError.

  6. Optionally, throw a "NotAllowedError" DOMException.

    Note: This implementation-defined condition is intended to allow user agents to decline for a number of reasons, for example the seller's site not being enrolled.

  7. Let p be a new promise.

  8. Let configMapping be global’s associated Document's node navigable's traversable navigable's fenced frame config mapping.

  9. Let pendingConfig be the result of constructing a pending fenced frame config with auctionConfig.

  10. Let urn be the result of running store a pending config on configMapping with pendingConfig.

  11. If urn is failure, then resolve p with null and return p.

  12. Let bidIgs be a new list of interest groups.

  13. If config["signal"] exists, then:

    1. Let signal be config["signal"].

    2. If signal is aborted, then reject p with signal’s abort reason and return p.

    3. Add the following abort steps to signal:

      1. Reject p with signal’s abort reason.

      2. Run update bid counts with bidIgs.

      3. Run interest group update with auctionConfig’s interest group buyers.

  14. Let queue be the result of starting a new parallel queue.

  15. Enqueue the following steps to queue:

    1. Let bidDebugReportInfoList be a new list of bid debug reporting info.

    2. Let winnerInfo be the result of running generate and score bids with auctionConfig, null, global, settings’s top-level origin, bidIgs, and bidDebugReportInfoList.

    3. Let auctionReportInfo be a new auction report info.

    4. If winnerInfo is not failure, then set auctionReportInfo to the result of running collect forDebuggingOnly reports with bidDebugReportInfoList and winnerInfo.

    5. If winnerInfo is failure, then queue a global task on DOM manipulation task source, given global, to reject p with a "TypeError".

    6. Otherwise if winnerInfo is null or winnerInfo’s leading bid is null:

      1. Queue a global task on DOM manipulation task source, given global, to resolve p with null.

      2. For each reportUrl of auctionReportInfo’s debug loss report urls:

        1. Send report to reportUrl.

    7. Otherwise:

      1. Let winner be winnerInfo’s leading bid.

      2. Let fencedFrameConfig be the result of filling in a pending fenced frame config with pendingConfig, auctionConfig, winnerInfo, and auctionReportInfo.

      3. Finalize a pending config on configMapping with urn and fencedFrameConfig.

      4. Wait until auctionConfig’s resolve to config is a boolean.

      5. Let result be fencedFrameConfig.

      6. If auctionConfig’s resolve to config is false, then set result to urn.

      7. Queue a global task on the DOM manipulation task source, given global, to resolve p with result.

    8. Run interest group update with auctionConfig’s interest group buyers.

    9. Run update bid counts with bidIgs.

    10. Run update previous wins with winner.

  16. Return p.

To construct a pending fenced frame config given an auction config config:

  1. Return a fenced frame config with the following items:

    mapped url

    a struct with the following items:

    value

    "about:blank"

    visibility

    "opaque"

    container size

    TODO: fill this in once container size is spec’d to be in config

    content size

    null

    interest group descriptor

    a struct with the following items:

    value

    a struct with the following items:

    owner

    ""

    name

    ""

    visibility

    "opaque"

    on navigate callback

    null

    effective sandbox flags

    a struct with the following items:

    value

    TODO: fill this in once fenced frame sandbox flags are more fully specified

    visibility

    "opaque"

    effective enabled permissions

    a struct with the following items:

    value

    «"attribution-reporting", "private-aggregation", "shared-storage", "shared-storage-select-url

    visibility

    "opaque"

    fenced frame reporting metadata

    null

    exfiltration budget metadata

    null

    nested configs

    a struct with the following items:

    value

    an empty list «»

    visibility

    "opaque"

    embedder shared storage context

    null

To fill in a pending fenced frame config given a fenced frame config pendingConfig, auction config auctionConfig, leading bid info winningBidInfo, and auction report info auctionReportInfo:

  1. Let winningBid be winningBidInfo’s leading bid.

  2. Let replacements be an ordered map whose keys are strings and whose values are strings.

  3. For each replacement in auctionConfig’s deprecated render url replacements:

    1. Let k be replacement’s match.

    2. Let v be replacement’s replacement.

    3. Set replacements[k] to v.

  4. Let replacedAdURL be the result of running substitute macros with replacements and winningBid’s ad descriptor's url.

  5. Set pendingConfig’s mapped url's value to replacedAdURL.

  6. Let adSize be winningBid’s ad descriptor's size.

  7. Let concreteAdSize be the result of

    resolving screen-relative sizes to pixel values for adSize. (WICG/turtledove#986)

  8. Let adWidthString and adHeightString be the result of

    converting concreteAdSize to strings. (WICG/turtledove#986)

  9. Let sizeMacroMap be the ordered map «[ "{%AD_WIDTH%}" → adWidthString, "{%AD_HEIGHT%}" → adHeightString, "${AD_WIDTH}" → adWidthString, "${AD_HEIGHT}" → adHeightString

  10. Set pendingConfig’s mapped url's value to the result of substituting macros with sizeMacroMap into winningBid’s ad descriptor's url.

  11. If adSize is not null:

    1. Set pendingConfig’s content size to a struct with the following items:

      value

      concreteAdSize.

      Cast concreteAdSize into the format that is eventually chosen for value. (WICG/turtledove#986)

      visibility

      "opaque"

  12. Set pendingConfig’s interest group descriptor's value to a struct with the following items:

    owner

    winningBid’s interest group's owner

    name

    winningBid’s interest group's name

  13. Let fencedFrameReportingMap be the map «[ "buyer" → «», "seller" → «» ]».

  14. If auctionConfig’s component auctions is empty, then set fencedFrameReportingMap["component-seller"] to an empty list «».

  15. Set pendingConfig’s fenced frame reporting metadata to a struct with the following items:

    value

    A struct with the following items:

    fenced frame reporting map

    fencedFrameReportingMap

    direct seller is seller

    true if auctionConfig’s component auctions is empty, false otherwise

    allowed reporting origins

    winningBid’s bid ad's allowed reporting origins

    visibility

    "opaque"

  16. Set pendingConfig’s on navigate callback to an algorithm with these steps:

    1. Asynchronously finish reporting with pendingConfig’s fenced frame reporting metadata's value's fenced frame reporting map, winningBidInfo and auctionReportInfo.

  17. Let adComponentDescriptorsWithReplacements be a new list of ad descriptors.

  18. If winningBid’s ad component descriptors is not null:

    1. For each adComponentDescriptor of winningBid’s ad component descriptors:

      1. Let descriptorWithReplacement be a new ad descriptor.

      2. Set descriptorWithReplacement’s size to adComponentDescriptor’s size.

      3. Set descriptorWithReplacement’s url to the result of running substitute macros with replacements and adComponentDescriptor’s url.

      4. Append descriptorWithReplacement to adComponentDescriptorsWithReplacements.

  19. Set pendingConfig’s nested configs's value to the result of running create nested configs with adComponentDescriptorsWithReplacements.

  20. Return pendingConfig.

To asynchronously finish reporting given a fenced frame reporting map reportingMap, leading bid info leadingBidInfo, and auction report info auctionReportInfo.

  1. Increment a winning bid’s k-anonymity count given leadingBidInfo’s leading bid.

  2. If leadingBidInfo’s leading non-k-anon-enforced bid is not null, and leadingBidInfo’s leading non-k-anon-enforced bid's idleadingBidInfo’s leading bid's id, increment a winning bid’s k-anonymity count given leadingBidInfo’s leading non-k-anon-enforced bid.

  3. Let buyerDone, sellerDone, and componentSellerDone be booleans, initially false.

  4. If leadingBidInfo’s component seller is null, set componentSellerDone to true.

  5. While:

    1. If buyerDone, sellerDone, and componentSellerDone are all true, then break.

    2. Wait until one of the following fields of leadingBidInfo being not null:

    3. If buyerDone is false and leadingBidInfo’s buyer reporting result is not null:

      1. Let buyerMap be leadingBidInfo’s buyer reporting result's reporting beacon map.

      2. If buyerMap is null, set buyerMap to an empty map «[]».

      3. Let macroMap be leadingBidInfo’s buyer reporting result's reporting macro map.

      4. Finalize a reporting destination with reportingMap, buyer, buyerMap, and macroMap.

      5. Send report to leadingBidInfo’s buyer reporting result's report url.

      6. Set buyerDone to true.

    4. If sellerDone is false and leadingBidInfo’s seller reporting result is not null:

      1. Let sellerMap be leadingBidInfo’s seller reporting result's reporting beacon map.

      2. If sellerMap is null, set sellerMap to an empty map «[]».

      3. Finalize a reporting destination with reportingMap, seller, and sellerMap.

      4. Send report to leadingBidInfo’s seller reporting result's report url.

      5. Set sellerDone to true.

    5. If componentSellerDone is false and leadingBidInfo’s component seller reporting result is not null:

      1. Let componentSellerMap be leadingBidInfo’s component seller reporting result's reporting beacon map.

      2. If componentSellerMap is null, set componentSellerMap to an empty map «[]».

      3. Finalize a reporting destination with reportingMap, component-seller, and componentSellerMap.

      4. Send report to leadingBidInfo’s component seller reporting result's report url.

      5. Set componentSellerDone to true.

  6. For each reportUrl of auctionReportInfo’s debug win report urls:

    1. Send report to report.

  7. For each reportUrl of auctionReportInfo’s debug loss report urls:

    1. Send report to report.

To create nested configs given ad component descriptors adComponentDescriptors:

  1. Let nestedConfigs be an empty list «».

  2. If adComponentDescriptors is null:

    1. Return nestedConfigs.

  3. For each adComponentDescriptor of adComponentDescriptors:

    1. Let fencedFrameConfig be a fenced frame config with the following items:

      mapped url

      a struct with the following items:

      value

      adComponentDescriptor’s url

      visibility

      "opaque"

      container size

      null

      content size

      If adComponentDescriptor’s size is null, then null. Otherwise, a struct with the following items:

      value

      adComponentDescriptor’s size TODO: Resolve screen-relative sizes and macros and cast this properly.

      visibility

      "opaque"

      interest group descriptor

      null

      on navigate callback

      null

      effective sandbox flags

      a struct with the following items:

      value

      TODO: fill this in once fenced frame sandbox flags are more fully specified

      visibility

      "opaque"

      effective enabled permissions

      a struct with the following items:

      value

      «"attribution-reporting", "private-aggregation", "shared-storage", "shared-storage-select-url

      visibility

      "opaque"

      fenced frame reporting metadata

      null

      exfiltration budget metadata

      null

      nested configs

      a struct with the following items:

      value

      an empty list «»

      visibility

      "opaque"

      embedder shared storage context

      null

    2. Append fencedFrameConfig to nestedConfigs.

  4. Return nestedConfigs.

To validate and convert auction ad config given an AuctionAdConfig config and a boolean isTopLevel:

  1. Assert that these steps are not running in parallel.

  2. Let auctionConfig be a new auction config.

  3. Let seller be the result of parsing an https origin with config["seller"].

  4. If seller is failure, then return failure.

  5. Set auctionConfig’s seller to seller.

  6. Let decisionLogicURL be the result of running the URL parser on config["decisionLogicURL"].

  7. If decisionLogicURL is failure, or it is not same origin with auctionConfig’s seller, then return failure.

  8. Set auctionConfig’s decision logic url to decisionLogicURL.

  9. If config["trustedScoringSignalsURL"] exists:

    1. Let trustedScoringSignalsURL be the result of running the URL parser on config["trustedScoringSignalsURL"].

    2. If trustedScoringSignalsURL is failure, or it is not same origin with auctionConfig’s seller, then return failure.

    3. Assert: trustedScoringSignalsURL’s scheme is "https".

    4. Set auctionConfig’s trusted scoring signals url to trustedScoringSignalsURL.

  10. If config["maxTrustedScoringSignalsURLLength"] exists:

    1. If config["maxTrustedScoringSignalsURLLength"] ≥ 0, set auctionConfig’s max trusted scoring signals url length to config["maxTrustedScoringSignalsURLLength"], otherwise throw a TypeError.

  11. If config["interestGroupBuyers"] exists:

    1. Let buyers be a new empty list.

    2. For each buyerString in config["interestGroupBuyers"]:

      1. Let buyer be the result of parsing an https origin with buyerString.

      2. If buyer is failure, then return failure.

      3. Append buyer to buyers.

    3. Set auctionConfig’s interest group buyers to buyers.

  12. If config["auctionSignals"] exists:

    1. Set auctionConfig’s auction signals to config["auctionSignals"].

    2. Handle an input promise in configuration given auctionConfig and auctionConfig’s auction signals:

  13. If config["requestedSize"] exists:

    1. Let adSize be the result from running parse an AdRender ad size with config["requestedSize"]

    2. If adSize is null, throw a TypeError.

    3. Set auctionConfig’s requested size to adSize.

  14. If config["allSlotsRequestedSizes"] exists:

    1. If config["allSlotsRequestedSizes"] is empty, throw a TypeError.

    2. Set auctionConfig’s all slots requested sizes to a new set.

    3. For each adSizeValue in config["allSlotsRequestedSizes"]:

      1. Let adSize be the result of running parse an AdRender ad size with adSizeValue.

      2. If adSize is null, throw a TypeError.

      3. If auctionConfig’s all slots requested sizes contains adSize, throw a TypeError.

      4. Append adSize to auctionConfig’s all slots requested sizes.

    4. If auctionConfig’s requested size is not null, and auctionConfig’s all slots requested sizes does not contain auctionConfig’s requested size, throw a TypeError.

  15. If config["sellerSignals"] exists:

    1. Set auctionConfig’s seller signals to config["sellerSignals"].

    2. Handle an input promise in configuration given auctionConfig and auctionConfig’s seller signals:

  16. If config["auctionNonce"] exists, then set auctionConfig’s auction nonce to the result of running get uuid from string with config["auctionNonce"].

  17. If config["additionalBids"] exists:

    1. Throw a TypeError if any of the following conditions hold:

    2. Set auctionConfig’s expects additional bids to true.

    3. Handle an input promise in configuration given auctionConfig and config["additionalBids"]:

      Note: The JavaScript code calling runAdAuction() is responsible for not resolving config["additionalBids"] until additional bids have been retrieved from one or more `Ad-Auction-Additional-Bid` headers, as resolving this Promise early would cause a race condition in which additional bids might not be included in the auction. There are two ways that additional bids can be retrieved. The first is for the JavaScript code to issue a request whose initiator type is "fetch" and whose adAuctionHeaders option is set to true. The JavaScript code has to resolve config["additionalBids"] after the corresponding call to fetch() has resolved to a response. The JavaScript code can also choose to wait to call runAdAuction() until after the corresponding call to fetch() has resolved to a response, and can then immediately resolve config["additionalBids"].

      The second way that additional bids can be retrieved is by issuing an iframe navigation request with the adauctionheaders content attribute set to true. In this case, the JavaScript code is retrieved as part of the iframe navigation response, at which point the JavaScript code in the iframe makes the call to runAdAuction(), and config["additionalBids"] can be immediately resolved.

  18. If config["directFromSellerSignalsHeaderAdSlot"] exists:

    1. Handle an input promise in configuration given auctionConfig and config["directFromSellerSignalsHeaderAdSlot"]:

      Note: The JavaScript code calling runAdAuction() is responsible for not resolving config["directFromSellerSignalsHeaderAdSlot"] until direct from seller signals have been retrieved from one or more `Ad-Auction-Signals` headers, as resolving this Promise early would cause a race condition in which the script runners might run without the direct from seller signals that it needs. There are two ways that direct from seller signals can be retrieved. The first is for the JavaScript code to issue a request whose initiator type is "fetch" and whose adAuctionHeaders option is set to true. The JavaScript code has to resolve config["directFromSellerSignalsHeaderAdSlot"] after the corresponding call to fetch() has resolved to a response. The JavaScript code can also choose to wait to call runAdAuction() until after the corresponding call to fetch() has resolved to a response, and can then immediately resolve config["directFromSellerSignalsHeaderAdSlot"]. The second way that direct from seller signals can be retrieved is by issuing an iframe navigation request with the adauctionheaders content attribute set to true. In this case, the JavaScript code is retrieved as part of the iframe navigation response, at which point the JavaScript code in the iframe makes the call to runAdAuction(), and config["directFromSellerSignalsHeaderAdSlot"] can be can be specified directly without a Promise.

  19. If config["deprecatedRenderURLReplacements"] exists:

    1. Set auctionConfig’s deprecated render url replacements to config["deprecatedRenderURLReplacements"].

    2. Handle an input promise in configuration given auctionConfig and auctionConfig’s deprecated render url replacements:

  20. If config["sellerTimeout"] exists, set auctionConfig’s seller timeout to config["sellerTimeout"] in milliseconds or 500, whichever is smaller.

  21. Let reportingTimeout be config["reportingTimeout"] if it exists, 50 otherwise.

  22. Set config["reportingTimeout"] to reportingTimeout in milliseconds or 5000, whichever is smaller.

  23. If config["sellerExperimentGroupId"] exists, then set auctionConfig’s seller experiment group id to config["sellerExperimentGroupId"].

  24. If config["sellerCurrency"] exists:

    1. If the result of checking whether a string is a valid currency tag on config["sellerCurrency"] is false, then return failure.

    2. Set auctionConfig’s seller currency to config["sellerCurrency"].

  25. If config["perBuyerSignals"] exists:

    1. Set auctionConfig’s per buyer signals to config["perBuyerSignals"].

    2. Handle an input promise in configuration given auctionConfig and auctionConfig’s per buyer signals:

  26. For each idlTimeoutMember, perBuyerTimeoutField, allBuyersTimeoutField in the following table

    IDL timeout member Per buyer timeout field All buyers timeout field
    "perBuyerTimeouts" per buyer timeouts all buyers timeout
    "perBuyerCumulativeTimeouts" per buyer cumulative timeouts all buyers cumulative timeout
    1. If config contains idlTimeoutMember:

      1. Set auctionConfig’s perBuyerTimeoutField to config[idlTimeoutMember].

      2. Handle an input promise in configuration given auctionConfig and auctionConfig’s perBuyerTimeoutField:

        • To parse the value result:

          1. Set auctionConfig’s perBuyerTimeoutField to a new ordered map whose keys are origins and whose values are durations in milliseconds.

          2. For each keyvalue of result:

            1. If perBuyerTimeoutField is "perBuyerTimeouts", and value > 500, then set value to 500.

            2. If key is "*", then set auctionConfig’s allBuyersTimeoutField to value in milliseconds, and continue.

            3. Let buyer be the result of parsing an https origin with key. If buyer is failure, throw a TypeError.

            4. Set auctionConfig’s perBuyerTimeoutField[buyer] to value in milliseconds.

        • To handle an error, set auctionConfig’s perBuyerTimeoutField to failure.

  27. If config["perBuyerGroupLimits"] exists, for each keyvalue of config["perBuyerGroupLimits"]:

    1. If value is 0, then return failure.

    2. If key is "*", then set auctionConfig’s all buyers group limit to value, and continue.

    3. Let buyer be the result of parsing an https origin with key.

    4. If buyer is failure, then return failure.

    5. Set auctionConfig’s per buyer group limits[buyer] to value.

  28. If config["perBuyerExperimentGroupIds"] exists, for each keyvalue of config["perBuyerExperimentGroupIds"]:

    1. If key is "*", then set auctionConfig’s all buyer experiment group id to value, and continue.

    2. Let buyer the result of parsing an https origin with key.

    3. If buyer is failure, then return failure.

    4. Set auctionConfig’s per buyer experiment group ids[buyer] to value.

  29. If config["perBuyerPrioritySignals"] exists, for each keyvalue of config["perBuyerPrioritySignals"]:

    1. Let signals be an ordered map whose keys are strings and whose values are double.

    2. for each kv of value:

      1. If k starts with "browserSignals.", throw a TypeError.

      2. Set signals[k] to v.

    3. If key is "*", then set auctionConfig’s all buyers priority signals to value, and continue.

    4. Let buyer be the result of parsing an https origin with key.

    5. If buyer is failure, then return failure.

    6. Set auctionConfig’s per buyer priority signals[buyer] to signals.

  30. If config["requiredSellerCapabilities"] exists:

    1. Let sellerCapabilities be a new set of seller capabilities.

    2. For each capabilityString of config["requiredSellerCapabilities"]:

      1. If capabilityString is "interest-group-counts" or "latency-stats", then append capabilityString to sellerCapabilities.

        Note: For forward compatibility with new values, don’t throw.

    3. Set auctionConfig’s required seller capabilities to sellerCapabilities.

  31. If config["perBuyerCurrencies"] exists:

    1. Set auctionConfig’s per buyer currencies to config["perBuyerCurrencies"]

    2. Handle an input promise in configuration given auctionConfig and auctionConfig’s per buyer currencies:

  32. If config["componentAuctions"] is not empty:

    1. If config["interestGroupBuyers"] exists and is not empty, then return failure.

    2. If config["deprecatedRenderURLReplacements"] exists, then throw a TypeError.

  33. For each component in config["componentAuctions"]:

    1. If isTopLevel is false, then return failure.

    2. Let componentAuction be the result of running validate and convert auction ad config with component and false.

    3. If componentAuction is failure, then return failure.

    4. Append componentAuction to auctionConfig’s component auctions.

  34. Set auctionConfig’s config idl to config.

  35. If config["resolveToConfig"] exists:

    1. Let auctionConfig’s resolve to config be config["resolveToConfig"].

    2. TODO: What should happen if this rejects?

    3. Upon fulfillment of auctionConfig’s resolve to config with resolveToConfig, set auctionConfig’s resolve to config to resolveToConfig.

  36. Return auctionConfig.

To validate a url macro given a string macro:

  1. Return true if any of the following conditions hold:

  2. Otherwise, return false.

To update bid count given a list of interest groups igs:

  1. For each ig in igs:

    1. Let loadedIg be the interest group from the user agent's interest group set whose owner is ig’s owner and whose name is ig’s name, continue if none found.

    2. If the most recent entry in loadedIg’s bid counts corresponds to the current day in UTC, increment its count. If not, insert a new tuple of the time set to the current UTC day and a count of 1.

    3. Replace the interest group that has loadedIg’s owner and name in the user agent's interest group set with loadedIg.

To update previous wins given a generated bid bid:

  1. Let ig be bid’s interest group.

  2. Let loadedIg be the interest group from the user agent's interest group set whose owner is ig’s owner and whose name is ig’s name, return if none found.

  3. Let win be a new previous win.

  4. Set win’s time to the current wall time.

  5. Let ad be an interest group ad whose render url is bid’s bid ad's render url, and whose metadata is bid’s bid ad's metadata.

  6. Set win’s ad json to the result of serializing an Infra value to a JSON string given ad.

  7. Append win to loadedIg’s previous wins.

  8. Replace the interest group that has loadedIg’s owner and name in the user agent's interest group set with loadedIg.

To build bid generators map given an auction config auctionConfig:

  1. Let bidGenerators be a new ordered map whose keys are origins and whose values are per buyer bid generators.

  2. Let negativeTargetInfo be a new negative target info.

  3. For each buyer in auctionConfig’s interest group buyers:

    1. For each ig of the user agent's interest group set whose owner is buyer:

      1. Let igName be ig’s name.

      2. If ig’s additional bid key is not null:

        1. Set negativeTargetInfo[(buyer, igName)] to (ig’s joining origin, ig’s additional bid key).

      3. Continue if any of the following conditions hold:

      4. Let signalsUrl be ig’s trusted bidding signals url.

      5. Let slotSizeQueryParam be the result of calculating the ad slot size query param given ig and auctionConfig.

      6. Let joiningOrigin be ig’s joining origin.

      7. If bidGenerators does not contain buyer:

        1. Let perBuyerGenerator be a new per buyer bid generator.

        2. Let perSignalsUrlGenerator be a new per signals url bid generator.

        3. Set perSignalsUrlGenerator[joiningOrigin] to « ig ».

        4. Set perSlotSizeQueryParam[slotSizeQueryParam] to perSignalsUrlGenerator.

        5. Set perBuyerGenerator[signalsUrl] to perSlotSizeQueryParam.

        6. Set bidGenerators[buyer] to perBuyerGenerator.

        7. TODO: add a perBiddingScriptUrlGenerator layer that replaces the list of IGs with a map from biddingScriptUrl to a list of IGs.

      8. Otherwise:

        1. Let perBuyerGenerator be bidGenerators[buyer].

        2. If perBuyerGenerator does not contain signalsUrl:

          1. Let perSignalsUrlGenerator be a new per signals url bid generator.

          2. Set perSignalsUrlGenerator[joiningOrigin] to « ig ».

          3. Set perSlotSizeQueryParam[slotSizeQueryParam] to perSignalsUrlGenerator.

          4. Set perBuyerGenerator[signalsUrl] to perSlotSizeQueryParam.

        3. Otherwise:

          1. Let perSlotSizeQueryParam be perBuyerGenerator[signalsUrl].

          2. If perSlotSizeQueryParam does not contain slotSizeQueryParam:

            1. Let perSignalsUrlGenerator be a new per signals url bid generator.

            2. Set perSignalsUrlGenerator[joiningOrigin] to « ig ».

            3. Set perSlotSizeQueryParam[slotSizeQueryParam] to perSignalsUrlGenerator.

          3. Otherwise:

            1. Let perSignalsUrlGenerator be perSlotSizeQueryParam[slotSizeQueryParam].

            2. If perSignalsUrlGenerator does not contain joiningOrigin, then set perSignalsUrlGenerator[joiningOrigin] to « ig ».

            3. Otherwise, append ig to perSignalsUrlGenerator[joiningOrigin].

  4. Return « bidGenerators, negativeTargetInfo ».

To check if required seller capabilities are permitted given an auction config auctionConfig and an interest group ig:

  1. Let seller be auctionConfig’s seller.

  2. Let requiredSellerCapabilities be auctionConfig’s required seller capabilities.

  3. Return true if all of the following conditions hold:

  4. Return false.

To generate a bid given an ordered map allTrustedBiddingSignals, a string auctionSignals, a BiddingBrowserSignals browserSignals, a string-or-null perBuyerSignals, a DirectFromSellerSignalsForBuyer directFromSellerSignalsForBuyer, a duration perBuyerTimeout in milliseconds, a currency tag expectedCurrency, an interest group ig, and a moment auctionStartTime:

  1. Let igGenerateBid be the result of building an interest group passed to generateBid with ig.

  2. Set browserSignals["joinCount"] to the sum of ig’s join counts for all days within the last 30 days.

  3. Set browserSignals["recency"] to the current wall time minus ig’s join time, in milliseconds.

  4. Set browserSignals["bidCount"] to the sum of ig’s bid counts for all days within the last 30 days.

  5. Set browserSignals["adComponentsLimit"] to 40.

  6. Let prevWins be a new sequence<PreviousWin>.

  7. For each prevWin of ig’s previous wins for all days within the the last 30 days:

    1. Let timeDelta be auctionStartTime minus prevWin’s time.

    2. Set timeDelta to 0 if timeDelta is negative, timeDelta’s nearest second (rounding down) otherwise.

    3. Let prevWinIDL be a new PreviousWin.

    4. Set prevWinIDL["timeDelta"] to timeDelta.

    5. Set prevWinIDL["adJSON"] to prevWin’s ad json.

    6. Append prevWinIDL to prevWins.

  8. Set browserSignals["prevWinsMs"] to prevWins.

  9. Let biddingScript be the result of fetching script with ig’s bidding url.

  10. If biddingScript is failure, return failure.

  11. If ig’s bidding wasm helper url is not null:

    1. Let wasmModuleObject be the result of fetching WebAssembly with ig’s bidding wasm helper url.

    2. If wasmModuleObject is not failure, then set browserSignals["wasmHelper"] to wasmModuleObject.

  12. Let trustedBiddingSignals be an ordered map whose keys are strings and whose values are any.

  13. For each key of ig’s trusted bidding signals keys:

    1. If allTrustedBiddingSignals is an ordered map and allTrustedBiddingSignals[key] exists, then set trustedBiddingSignals[key] to allTrustedBiddingSignals[key].

  14. Return the result of evaluating a bidding script with biddingScript, ig, expectedCurrency, igGenerateBid, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals, directFromSellerSignalsForBuyer, and perBuyerTimeout.

To generate and score bids given an auction config auctionConfig, an auction config-or-null topLevelAuctionConfig, a global object global, an origin topLevelOrigin, a list of interest groups bidIgs, and a list of bid debug reporting info bidDebugReportInfoList:

  1. Assert that these steps are running in parallel.

  2. Let auctionStartTime be the current wall time.

  3. Let decisionLogicScript be the result of fetching script with auctionConfig’s decision logic url.

  4. If decisionLogicScript is failure, return null.

  5. Let seller be auctionConfig’s seller.

  6. Let « bidGenerators, negativeTargetInfo » be the result of running build bid generators map with auctionConfig.

  7. Let leadingBidInfo be a new leading bid info.

  8. Let queue be the result of starting a new parallel queue.

  9. Let capturedAuctionHeaders be global’s associated Document’s node navigable’s traversable navigable’s captured ad auction signals headers.

  10. If auctionConfig’s component auctions are not empty:

    1. Assert topLevelAuctionConfig is null.

    2. Let pendingComponentAuctions be auctionConfig’s component auctions's size.

    3. Let topLevelDirectFromSellerSignalsForSeller be null.

    4. Let topLevelDirectFromSellerSignalsRetrieved be false.

    5. For each component in auctionConfig’s component auctions, enqueue the following steps to queue:

      1. Let compWinnerInfo be the result of running generate and score bids with component, auctionConfig, global, topLevelOrigin, bidIgs, and bidDebugReportInfoList.

      2. If compWinnerInfo is failure, return failure.

      3. If recursively wait until configuration input promises resolve given auctionConfig returns failure, return failure.

      4. If topLevelDirectFromSellerSignalsRetrieved is false:

        1. Let topLevelDirectFromSellerSignals be the result of running get direct from seller signals given seller, auctionConfig’s direct from seller signals header ad slot, and capturedAuctionHeaders.

        2. Let topLevelDirectFromSellerSignalsForSeller be the result of running get direct from seller signals for a seller given topLevelDirectFromSellerSignals.

        3. Set topLevelDirectFromSellerSignalsRetrieved to true.

      5. If compWinnerInfo’s leading bid is not null, then run score and rank a bid with auctionConfig, compWinnerInfo’s leading bid, leadingBidInfo, decisionLogicScript, null, "top-level-auction", null, and topLevelOrigin.

      6. If compWinnerInfo’s leading non-k-anon-enforced bid is not null, then run score and rank a bid with auctionConfig, compWinnerInfo’s leading non-k-anon-enforced bid, leadingBidInfo, decisionLogicScript, null, "top-level-auction", null, and topLevelOrigin.

      7. Decrement pendingComponentAuctions by 1.

    6. Wait until pendingComponentAuctions is 0.

    7. If leadingBidInfo’s leading bid is null, return null.

    8. Let winningComponentConfig be leadingBidInfo’s auction config.

    9. Set leadingBidInfo’s auction config to auctionConfig.

    10. Set leadingBidInfo’s component seller to winningComponentConfig’s seller.

    11. Let « topLevelSellerSignals, unusedTopLevelReportResultBrowserSignals » be the result of running report result with leadingBidInfo, topLevelDirectFromSellerSignalsForSeller, winningComponentConfig, and global.

    12. Set leadingBidInfo’s auction config to winningComponentConfig.

    13. Set leadingBidInfo’s component seller to null.

    14. Set leadingBidInfo’s top level seller to seller.

    15. Set leadingBidInfo’s top level seller signals to topLevelSellerSignals.

    16. Let directFromSellerSignals be the result of running get direct from seller signals given winningComponentConfig’s seller, winningComponentConfig’s direct from seller signals header ad slot, and capturedAuctionHeaders.

    17. Let directFromSellerSignalsForSeller be the result of running get direct from seller signals for a seller given directFromSellerSignals.

    18. Let directFromSellerSignalsForBuyer be the result of running get direct from seller signals for a buyer with directFromSellerSignals, and leadingBidInfo’s leading bid's interest group's owner.

    19. Let « sellerSignals, reportResultBrowserSignals » be the result of running report result with leadingBidInfo, directFromSellerSignalsForSeller, null, and global.

    20. Run report win with leadingBidInfo, sellerSignals, reportResultBrowserSignals, and directFromSellerSignalsForBuyer.

    21. Return leadingBidInfo.

  11. If waiting until configuration input promises resolve given auctionConfig returns failure, then return failure.

  12. Let allBuyersExperimentGroupId be auctionConfig’s all buyer experiment group id.

  13. Let allBuyersGroupLimit be auctionConfig’s all buyers group limit.

  14. Let auctionSignals be auctionConfig’s auction signals.

  15. Let directFromSellerSignals be the result of running get direct from seller signals given seller, auctionConfig’s direct from seller signals header ad slot, and capturedAuctionHeaders.

  16. Let directFromSellerSignalsForSeller be the result of running get direct from seller signals for a seller given directFromSellerSignals.

  17. Let browserSignals be a BiddingBrowserSignals.

  18. Let topLevelHost be the result of running the host serializer on topLevelOrigin’s host.

  19. Set browserSignals["topWindowHostname"] to topLevelHost.

  20. Set browserSignals["seller"] to the serialization of seller.

  21. Let auctionLevel be "single-level-auction".

  22. Let componentAuctionExpectedCurrency be null.

  23. If topLevelAuctionConfig is not null:

    1. Set browserSignals["topLevelSeller"]] to the serialization of topLevelAuctionConfig’s seller.

    2. Set auctionLevel to "component-auction".

    3. Set componentAuctionExpectedCurrency to the result of looking up per-buyer currency with topLevelAuctionConfig and seller.

  24. Let pendingBuyers be bidGenerators’s size.

  25. Let additionalBids be the result of running validate and convert additional bids with auctionConfig, topLevelAuctionConfig, negativeTargetInfo and global.

  26. Let pendingAdditionalBids be the size of additionalBids.

  27. For each additionalBid of additionalBids, run the following steps in parallel:

    1. Score and rank a bid with auctionConfig, additionalBid, leadingBidInfo, decisionLogicScript, null, auctionLevel, componentAuctionExpectedCurrency, and topLevelOrigin.

    2. Decrement pendingAdditionalBids by 1.

  28. Let settings be global’s relevant settings object.

  29. For each buyerperBuyerGenerator of bidGenerators, enqueue the following steps to queue:

    1. Let perBuyerCumulativeTimeout be auctionConfig’s all buyers cumulative timeout.

    2. If auctionConfig’s per buyer cumulative timeouts is not null and per buyer cumulative timeouts[buyer] exists, then set perBuyerCumulativeTimeout to auctionConfig’s per buyer cumulative timeouts[buyer].

    3. Let buyerExperimentGroupId be allBuyersExperimentGroupId.

    4. Let perBuyerExperimentGroupIds be auctionConfig’s per buyer experiment group ids.

    5. If perBuyerExperimentGroupIds is not null and perBuyerExperimentGroupIds[buyer] exists, then set buyerExperimentGroupId to perBuyerExperimentGroupIds[buyer].

    6. Apply interest groups limits to prioritized list:

      1. Let buyerGroupLimit be allBuyersGroupLimit.

      2. Let perBuyerGroupLimits be auctionConfig’s per buyer group limits.

      3. If perBuyerGroupLimits is not null and perBuyerGroupLimits[buyer] exists, then set buyerGroupLimit to perBuyerGroupLimits[buyer].

      4. Let igs be a new list of interest groups.

      5. For each signalsUrl → perSlotSizeQueryParam of perBuyerGenerator:

        1. For each slotSizeQueryParam → perSignalsUrlGenerator of perSlotSizeQueryParam:

          1. For each joiningOrigin → groups of perSignalsUrlGenerator:

            1. Extend igs with groups.

      6. Sort in descending order igs, with a being less than b if a’s priority is less than b’s priority.

      7. Remove the first buyerGroupLimit items from igs.

      8. For each signalsUrl → perSlotSizeQueryParam of perBuyerGenerator:

        1. For each slotSizeQueryParam → perSignalsUrlGenerator of perSlotSizeQueryParam:

          1. For each joiningOrigin → groups of perSignalsUrlGenerator:

            1. Remove from groups any interest group contained in igs.

    7. Let perBuyerSignals be null.

    8. If auctionConfig’s per buyer signals is not null and per buyer signals[buyer] exists, then set perBuyerSignals to auctionConfig’s per buyer signals[buyer].

    9. Let perBuyerTimeout be auctionConfig’s all buyers timeout.

    10. If auctionConfig’s per buyer timeouts is not null and per buyer timeouts[buyer] exists, then set perBuyerTimeout to auctionConfig’s per buyer timeouts[buyer].

    11. Let expectedCurrency be the result of looking up per-buyer currency with auctionConfig and buyer.

    12. Set browserSignals["forDebuggingOnlyInCooldownOrLockout"] to the result of running is debugging only in cooldown or lockout with buyer.

    13. For each signalsUrlperSignalsUrlGenerator of perSlotSizeQueryParam:

      1. For each slotSizeQueryParamperSlotSizeQueryParam of perBuyerGenerator:

        1. Let allTrustedBiddingSignals be an ordered map whose keys are strings, and values are strings.

        2. Let keys be a new ordered set.

        3. Let igNames be a new ordered set.

        4. Let lengthLimit be the maximum value that a long integer can hold.

        5. Let fetchSignalStartTime be settings’s current monotonic time.

        6. For each joiningOrigin → groups of perSignalsUrlGenerator:

          1. For each ig of groups:

            1. Let putativeKeys be a clone of keys.

            2. Let putativeIgNames be a clone of igNames.

            3. Let putativeLengthLimit be ig’s max trusted bidding signals url length.

            4. If ig’s max trusted bidding signals url length is 0 or &gt; lengthLimit, then set putativeLengthLimit to lengthLimit.

            5. Extend putativeKeys with ig’s trusted bidding signals keys.

            6. Append ig’s name to putativeIgNames.

            7. Let biddingSignalsUrl be the result of building trusted bidding signals url with signalsUrl, putativeKeys, putativeIgNames, buyerExperimentGroupId, topLevelOrigin, and slotSizeQueryParam.

            8. If serialized biddingSignalsUrl’s lengthputativeLengthLimit:

              1. Set keys to putativeKeys.

              2. Set igNames to putativeIgNames.

              3. Set lengthLimit to putativeLengthLimit.

            9. Otherwise:

              1. Let biddingSignalsUrl be the result of building trusted bidding signals url with signalsUrl, keys, igNames, buyerExperimentGroupId, topLevelOrigin, and slotSizeQueryParam.

              2. Let « partialTrustedBiddingSignals, dataVersion » be the result of fetching trusted signals with biddingSignalsUrl and true.

              3. For each keyvalue in partialTrustedBiddingSignals:

                1. Set allTrustedBiddingSignals[key] to value.

              4. Set keys to a clone of ig’s trusted bidding signals keys.

              5. Set igNames to « ig’s name ».

              6. Set ig’s max trusted bidding signals url length to lengthLimit.

          2. Let biddingSignalsUrl be the result of building trusted bidding signals url with signalsUrl, keys, igNames, buyerExperimentGroupId, topLevelOrigin, and slotSizeQueryParam.

          3. Let « partialTrustedBiddingSignals, dataVersion » be the result of fetching trusted signals with biddingSignalsUrl and true.

          4. For each keyvalue in partialTrustedBiddingSignals:

            1. Set allTrustedBiddingSignals[key] to value.

        7. If dataVersion is not null, then set browserSignals["dataVersion"] to dataVersion.

        8. Let fetchSignalDuration be the duration from fetchSignalStartTime to settings’s current monotonic time, in milliseconds.

        9. If perBuyerCumulativeTimeout is not null, then decrement perBuyerCumulativeTimeout by fetchSignalDuration.

        10. For each joiningOrigin → groups of perSignalsUrlGenerator:

          1. For each ig of groups:

            1. If perBuyerCumulativeTimeout is negative, then break.

            2. If ig’s bidding url is null, continue.

            3. If perBuyerCumulativeTimeout is not null and is less than perBuyerTimeout, then set perBuyerTimeout to perBuyerCumulativeTimeout.

            4. Let generateBidStartTime be settings’s current monotonic time.

            5. Let directFromSellerSignalsForBuyer be the result of running get direct from seller signals for a buyer with directFromSellerSignals, and ig’s owner.

            6. Let « generatedBid, bidDebugReportInfo » be the result of generate a bid given allTrustedBiddingSignals, auctionSignals, a clone of browserSignals, perBuyerSignals, directFromSellerSignalsForBuyer, perBuyerTimeout, expectedCurrency, ig, and auctionStartTime.

            7. Let generateBidDuration be the duration from generateBidStartTime to settings’s current monotonic time, in milliseconds.

            8. If perBuyerCumulativeTimeout is not null, decrement perBuyerCumulativeTimeout by generateBidDuration.

            9. If generatedBid is null:

              1. Register a bid for forDebuggingOnly reports given null, bidDebugReportInfo, and bidDebugReportInfoList.

              2. continue.

            10. Let bidsToScore be a new list of generated bids

            11. If query generated bid k-anonymity count given generatedBid returns true:

              1. Let bidCopy be a clone of generatedBid.

              2. Set bidCopy’s for k-anon auction to false.

              3. Append bidCopy to bidsToScore.

              4. Append generatedBid to bidsToScore.

                Note: Conceptually, a bid that’s already k-anonymous is considered for both the k-anonymous and non-enforcing-k-anonymity leadership.

              5. Register a bid for forDebuggingOnly reports given generatedBid, bidDebugReportInfo, and bidDebugReportInfoList.

            12. Otherwise:

              Note: Generate a bid is now rerun with only k-anonymous ads to give the buyer a chance to generate a bid for k-anonymous ads. Allowing the buyer to first generate a bid for non-k-anonymous ads provides a mechanism to bootstrap the k-anonymity count, otherwise no ads would ever trigger increment k-anonymity count and all ads would fail query k-anonymity count.

              1. Set generatedBid’s for k-anon auction to false.

              2. Append generatedBid to bidsToScore.

              3. Let originalAds be ig’s ads.

              4. If originalAds is not null:

                1. Set ig’s ads to a new list of interest group ad.

                2. For each ad in originalAds:

                  1. If query ad k-anonymity count given ig and ad’s render url returns true, append ad to ig’s ads.

              5. Let originalAdComponents be ig’s ad components.

              6. If originalAdComponents is not null:

                1. Set ig’s ad components to a new list of interest group ad.

                2. For each adComponent in originalAdComponents:

                  1. If query component ad k-anonymity count given adComponent’s render url returns true, append adComponent to ig’s ad components.

              7. If perBuyerCumulativeTimeout is not null and is < perBuyerTimeout, then set perBuyerTimeout to perBuyerCumulativeTimeout.

              8. Let generateBidStartTime be settings’s current monotonic time.

              9. Set « generatedBid, bidDebugReportInfo » to the result of generate a bid given allTrustedBiddingSignals, auctionSignals, a clone of browserSignals, perBuyerSignals, directFromSellerSignalsForBuyer, perBuyerTimeout, expectedCurrency, ig, and auctionStartTime.

              10. Set ig’s ads to originalAds.

              11. Set ig’s ad components to originalAdComponents.

              12. Let generateBidDuration be the duration from generateBidStartTime to settings’s current monotonic time, in milliseconds.

              13. If perBuyerCumulativeTimeout is not null, then decrement perBuyerCumulativeTimeout by generateBidDuration.

              14. If generatedBid is a generated bid:

                1. Assert that query generated bid k-anonymity count given generatedBid returns true.

                2. Append generatedBid to bidsToScore.

                3. Register a bid for forDebuggingOnly reports given generatedBid, bidDebugReportInfo and bidDebugReportInfoList.

              15. If generatedBid is null, register a bid for forDebuggingOnly reports given null, bidDebugReportInfo and bidDebugReportInfoList.

            13. For each bidToScore of bidsToScore:

              1. If bidToScore’s for k-anon auction is true, append bidToScore’s interest group to bidIgs.

              2. Score and rank a bid with auctionConfig, bidToScore, leadingBidInfo, decisionLogicScript, directFromSellerSignalsForSeller, dataVersion, auctionLevel, componentAuctionExpectedCurrency, and topLevelOrigin.

    14. Decrement pendingBuyers by 1.

  30. Wait until both pendingBuyers and pendingAdditionalBids are 0.

  31. If leadingBidInfo’s leading bid is null, return null.

  32. If topLevelAuctionConfig is null:

    1. Let « sellerSignals, reportResultBrowserSignals » be the result of running report result with leadingBidInfo, directFromSellerSignalsForSeller, null, and global.

    2. Let directFromSellerSignalsForWinner be the result of running get direct from seller signals for a buyer with directFromSellerSignals, and leadingBidInfo’s leading bid's interest group's owner.

    3. Run report win with leadingBidInfo, sellerSignals, reportResultBrowserSignals, and directFromSellerSignalsForWinner.

  33. Let replacements be an ordered map whose keys are strings and whose values are strings.

    1. For each ad keyword replacement, replacement, within deprecated render url replacements:

      1. Let k be replacement’s match.

      2. Let v be replacement’s replacement.

      3. Set replacements[k] to v.

  34. Set leadingBidInfo’s leading bid's ad descriptor to the result of substitute macros with replacements and leading bid's ad descriptor.

  35. If leadingBidInfo’s leading bid's ad descriptors is not null:

    1. For each ad descriptor, adDescriptor, within leading bid's ad descriptors:

      1. Set adDescriptor to the result of substitute macros with replacements and adDescriptor.

  36. Return leadingBidInfo.

To build an interest group passed to generateBid given an interest group ig:
  1. Let igGenerateBid be a new GenerateBidInterestGroup with the following fields:

    owner
    The serialization of ig’s owner
    name
    ig’s name
    enableBiddingSignalsPrioritization
    ig’s enable bidding signals prioritization
    priorityVector
    ig’s priority vector if not null, otherwise undefined
    executionMode
    ig’s execution mode
    biddingLogicURL
    The serialization-or-undefined of ig’s bidding url
    biddingWasmHelperURL
    The serialization of ig’s bidding wasm helper url
    updateURL
    The serialization of ig’s update url
    trustedBiddingSignalsURL
    The serialization of ig’s trusted bidding signals url
    trustedBiddingSignalsKeys
    ig’s trusted bidding signals keys
    trustedBiddingSignalsSlotSizeMode
    ig’s trusted bidding signals slot size mode
    maxTrustedBiddingSignalsURLLength
    ig’s max trusted bidding signals url length
    userBiddingSignals
    Parse a JSON string to a JavaScript value given ig’s user bidding signals
    ads
    ig’s ads converted to an AuctionAd sequence
    adComponents
    ig’s ad components converted to an AuctionAd sequence
  2. Return igGenerateBid.

To convert to an AuctionAd sequence given a list-or-null ads:
  1. If ads is null, then return undefined.

  2. Let adsIDL be a new sequence<AuctionAd>.

  3. For each ad of ads:

    1. Let adIDL be a new AuctionAd.

    2. Set adIDL["renderURL"] to the serialization of ad’s render url.

    3. If ad’s metadata is not null, then set adIDL["metadata"] to the result of parsing a JSON string to a JavaScript value given ad’s metadata.

    4. Append adIDL to adsIDL.

  4. Return adsIDL.

To score and rank a bid given an auction config auctionConfig, a generated bid generatedBid, a bid debug reporting info bidDebugReportInfo, a leading bid info leadingBidInfo, a string decisionLogicScript, a DirectFromSellerSignalsForSeller directFromSellerSignalsForSeller, an unsigned long-or-null biddingDataVersion, an enum auctionLevel, which is "single-level-auction", "top-level-auction", or "component-auction", a currency tag componentAuctionExpectedCurrency, and an origin topLevelOrigin:
  1. Let renderURL be serialized generatedBid’s ad descriptor's url.

  2. Let adComponentRenderURLs be a new empty list.

  3. If generatedBid’s ad component descriptors is not null:

    1. For each adComponentDescriptor in generatedBid’s ad component descriptors:

      1. Append serialized adComponentDescriptor’s url to adComponentRenderURLs.

  4. Let fullSignalsUrl be the result of building trusted scoring signals url with auctionConfig’s trusted scoring signals url, «renderURL», adComponentRenderURLs, auctionConfig’s seller experiment group id, and topLevelOrigin.

    Implementations may batch requests by collecting render URLs and ad component render URLs from multiple invocations of score and rank a bid and passing them all to a single invocation of building trusted scoring signals url to get a scoringSignalsUrl. By employing this approach, the length of serialized scoringSignalsUrl must not exceed the

    max trusted scoring signals url length of the auction. In cases where the length limit is exceeded, the request must be divided into smaller pieces to comply with the length restriction. However, note that a single request is always considered valid, regardless of whether its length exceeds the auction’s max trusted scoring signals url length.

    The network response has to be parsed to pull out the pieces relevant to each evaluation of a scoring script.

  5. Let trustedScoringSignals be null.

  6. Let «allTrustedScoringSignals, scoringDataVersion» be the result of fetching trusted signals with fullSignalsUrl and false.

  7. If allTrustedScoringSignals is an ordered map:

    1. Set trustedScoringSignals to a new empty map.

    2. Set trustedScoringSignals["renderURL"] to a new empty map.

    3. If allTrustedScoringSignals["renderURLs"] exists and allTrustedScoringSignals["renderURLs"][renderURL] exists, then set trustedScoringSignals["renderURL"][renderURL] to allTrustedScoringSignals["renderURLs"][renderURL].

    4. If adComponentRenderURLs is not empty:

      1. Let adComponentRenderURLsValue be a new empty map.

      2. If allTrustedScoringSignals["adComponentRenderURLs"] exists, for each adComponentRenderURL in adComponentRenderURLs:

        1. If allTrustedScoringSignals["adComponentRenderURLs"][adComponentRenderURL] exists, then set adComponentRenderURLsValue[adComponentRenderURL] to allTrustedScoringSignals["adComponentRenderURLs"][adComponentRenderURL].

      3. Set trustedScoringSignals["adComponentRenderURLs"] to adComponentRenderURLsValue.

  8. Let adMetadata be generatedBid’s ad.

  9. Let bidValue be generatedBid’s bid.

  10. If generatedBid’s modified bid is not null, then set bidValue to generatedBid’s modified bid.

  11. Let owner be generatedBid’s interest group's owner.

  12. Let seller be auctionConfig’s seller.

  13. Let browserSignals be a ScoringBrowserSignals with the following fields:

    topWindowHostname
    The result of running the host serializer on topLevelOrigin’s host
    interestGroupOwner
    Serialized owner
    renderURL
    The result of running the URL serializer on generatedBid’s ad descriptor's url
    biddingDurationMsec
    generatedBid’s bid duration
    bidCurrency
    The result of serializing a currency tag with generatedBid’s bid's currency
    dataVersion
    scoringDataVersion if it is not null, undefined otherwise
    adComponents
    generatedBid’s ad component descriptors converted to a string sequence
    forDebuggingOnlyInCooldownOrLockout
    The result of running is debugging only in cooldown or lockout with seller
  14. Let « scoreAdResult, debugWinReportUrl, debugLossReportUrl » be the result of evaluating a scoring script with decisionLogicScript, adMetadata, bidValue’s value, auctionConfig’s config idl, trustedScoringSignals, browserSignals, directFromSellerSignalsForSeller, and auctionConfig’s seller timeout.

  15. If auctionLevel is "top-level-auction":

    1. Set bidDebugReportInfo’s top level seller debug loss report url to debugLossReportUrl.

    2. Set bidDebugReportInfo’s top level seller debug win report url to debugWinReportUrl.

  16. Otherwise:

    1. Set bidDebugReportInfo’s seller debug loss report url to debugLossReportUrl.

    2. Set bidDebugReportInfo’s seller debug win report url to debugWinReportUrl.

  17. Let scoreAdOutput be result of processing scoreAd output with scoreAdResult.

  18. If auctionLevel is "component-auction", then set generatedBid’s component seller and bidDebugReportInfo’s component seller to seller.

  19. Return if any of the following conditions hold:

  20. If auctionLevel is "component-auction":

    1. Let bidToCheck be generatedBid’s bid.

    2. If scoreAdOutput["bid"] exists:

      1. Let modifiedBidValue be scoreAdOutput["bid"].

      2. If modifiedBidValue ≤ 0, return.

      3. Let modifiedBidCurrency be null.

      4. If scoreAdOutput["bidCurrency] exists, then set modifiedBidCurrency to scoreAdOutput["bidCurrency].

      5. Set generatedBid’s modified bid to a bid with currency with value modifiedBidValue and currency modifiedBidCurrency.

      6. Set bidToCheck to generatedBid’s modified bid.

    3. If the result of checking a currency tag with componentAuctionExpectedCurrency and bidToCheck’s currency is false, return.

    4. If the result of checking a currency tag with auctionConfig’s seller currency and bidToCheck’s currency is false, return.

  21. If auctionConfig’s seller currency is not null:

    1. If generatedBid’s bid's currency is equal to auctionConfig’s seller currency:

      1. Set generatedBid’s bid in seller currency to generatedBid’s bid's value.

      2. If scoreAdOutput["incomingBidInSellerCurrency"] exists and does not equal generatedBid’s bid in seller currency, return.

    2. Otherwise if scoreAdOutput["incomingBidInSellerCurrency"] exists, then set generatedBid’s bid in seller currency to scoreAdOutput["incomingBidInSellerCurrency"].

  22. Let score be scoreAdOutput["desirability"].

  23. If generatedBid’s for k-anon auction is false:

    1. Let updateLeadingNonKAnonEnforcedBid be false.

    2. If leadingBidInfo’s leading non-k-anon-enforced bid is null, or score > leadingBidInfo’s top non-k-anon-enforced score:

      1. Set updateLeadingNonKAnonEnforcedBid to true.

      2. Set leadingBidInfo’s top non-k-anon-enforced bids count to 1.

    3. If leadingBidInfo’s leading non-k-anon-enforced bid is not null and score = leadingBidInfo’s top non-k-anon-enforced score:

      1. Increment leadingBidInfo’s top non-k-anon-enforced bids count by 1.

      2. Set updateLeadingNonKAnonEnforcedBid to true with 1 in leadingBidInfo’s top non-k-anon-enforced bids count chance.

    4. If updateLeadingNonKAnonEnforcedBid is true:

      1. Set leadingBidInfo’s top non-k-anon-enforced score to score.

      2. Set leadingBidInfo’s leading non-k-anon-enforced bid to generatedBid.

    5. Return.

  24. Let updateLeadingBid be false.

  25. If leadingBidInfo’s leading bid is null, or score > leadingBidInfo’s top score:

    1. Set updateLeadingBid to true.

    2. Set leadingBidInfo’s top bids count to 1.

    3. Set leadingBidInfo’s at most one top bid owner to true.

  26. Otherwise if score equals leadingBidInfo’s top score:

    1. Increment leadingBidInfo’s top bids count by 1.

    2. Set updateLeadingBid to true with 1 in leadingBidInfo’s top bids count chance.

    3. If updateLeadingBid is false, then update highest scoring other bid with score, leadingBidInfo’s leading bid, and leadingBidInfo.

    4. If owner is not same origin with leadingBidInfo’s leading bid's interest group's owner, then set leadingBidInfo’s at most one top bid owner to false.

  27. Otherwise if score is greater than or equal to leadingBidInfo’s second highest score, then update highest scoring other bid with score, bidValue, and leadingBidInfo.

  28. If updateLeadingBid is true:

    1. If leadingBidInfo’s leading bid is not null, then update highest scoring other bid with leadingBidInfo’s top score, leadingBidInfo’s leading bid, and leadingBidInfo.

    2. Set leadingBidInfo’s top score to score.

    3. Set leadingBidInfo’s leading bid to generatedBid.

    4. Set leadingBidInfo’s auction config to auctionConfig.

    5. Set leadingBidInfo’s bidding data version to biddingDataVersion.

    6. Set leadingBidInfo’s scoring data version to scoringDataVersion.

To convert to a string sequence given a list-or-null adComponents:
  1. If adComponents is null, return undefined.

  2. Let result be a new sequence<USVString>.

  3. For each component of adComponents:

    1. Append serialized component’s url to result.

  4. Return result.

To update highest scoring other bid given a double score, a generated bid-or-null bid, and a leading bid info leadingBidInfo:
  1. If bid is null, return.

  2. Let owner be bid’s interest group's owner.

  3. If score is greater than leadingBidInfo’s second highest score:

    1. Set leadingBidInfo’s highest scoring other bid to bid.

    2. Set leadingBidInfo’s highest scoring other bids count to 1.

    3. Set leadingBidInfo’s second highest score to score.

    4. Set leadingBidInfo’s highest scoring other bid owner to owner if leadingBidInfo’s at most one top bid owner is true, null otherwise.

  4. Otherwise if score is equal to leadingBidInfo’s second highest score:

    1. Increment leadingBidInfo’s highest scoring other bids count by 1.

    2. Set leadingBidInfo’s highest scoring other bid to bid with 1 in leadingBidInfo’s highest scoring other bids count chance.

    3. If leadingBidInfo’s highest scoring other bid owner is not null and owner is not same origin with leadingBidInfo’s highest scoring other bid owner, then set leadingBidInfo’s highest scoring other bid owner to null.

The Ad-Auction-Allowed HTTP response header is a structured header whose value must be a boolean.

To validate fetching response given a response response, null, failure, or a byte sequence responseBody, and a string mimeType:
  1. If responseBody is null or failure, return false.

  2. If getting `Ad-Auction-Allowed` and "item" from response’s header list does not return a true value, return false.

  3. Let headerMimeType be the result of extracting a MIME type from response’s header list.

  4. Return false if any of the following conditions hold:

    • headerMimeType is failure;

    • mimeType is "text/javascript" and headerMimeType is not a JavaScript MIME type;

    • mimeType is "application/json" and headerMimeType is not a JSON MIME type.

  5. Let mimeTypeCharset be headerMimeType’s parameters["charset"].

  6. Return false if any of the following conditions hold:

    • mimeTypeCharset does not exist, or mimeTypeCharset is "utf-8", and responseBody is not UTF-8 encoded;

    • mimeTypeCharset is "us-ascii", and not all bytes in responseBody are ASCII bytes.

  7. Return true.

To fetch script given a URL url:
  1. Let request be a new request with the following properties:

    URL

    url

    header list

    «Accept: text/javascript»

    client

    null

    mode

    "no-cors"

    referrer

    "no-referrer"

    credentials mode

    "omit"

    redirect mode

    "error"

    One of the side-effects of a null client for this subresource request is it neuters all service worker interceptions, despite not having to set the service workers mode.

    Stop using "no-cors" mode where possible (WICG/turtledove#667).

  2. Let script be null.

  3. Fetch request with useParallelQueue set to true, and processResponseConsumeBody set to the following steps given a response response and null, failure, or a byte sequence responseBody:

    1. If validate fetching response with response, responseBody and "text/javascript" returns false, set script to failure and return.

    2. Set script to responseBody.

  4. Wait for script to be set.

  5. Return script.

To fetch WebAssembly given a URL url:
  1. Let request be a new request with the following properties:

    URL

    url

    header list

    «Accept: application/wasm»

    client

    null

    mode

    "no-cors"

    referrer

    "no-referrer"

    credentials mode

    "omit"

    redirect mode

    "error"

    One of the side-effects of a null client for this subresource request is it neuters all service worker interceptions, despite not having to set the service workers mode.

    Stop using "no-cors" mode where possible (WICG/turtledove#667).

  2. Let moduleObject be null.

  3. Fetch request with processResponseConsumeBody set to the following steps given a response response and null, failure, or a byte sequence responseBody:

    1. Set moduleObject to failure and return, if any of the following conditions hold:

    2. Let module be the result of compiling a WebAssembly module response.

    3. If module is error, set moduleObject to failure.

    4. Otherwise, set moduleObject to module.

  4. Wait for moduleObject to be set.

  5. Return moduleObject.

The Data-Version HTTP response header is a structured header whose value must be an integer. The X-fledge-bidding-signals-format-version HTTP response header is a structured header whose value must be an integer.

To fetch trusted signals given a URL url, and a boolean isBiddingSignal:
  1. Let request be a new request with the following properties:

    URL

    url

    header list

    «Accept: application/json»

    client

    null

    mode

    "no-cors"

    referrer

    "no-referrer"

    credentials mode

    "omit"

    redirect mode

    "error"

    One of the side-effects of a null client for this subresource request is it neuters all service worker interceptions, despite not having to set the service workers mode.

    Stop using "no-cors" mode where possible (WICG/turtledove#667).

  2. Let signals be null.

  3. Let dataVersion be null.

  4. Let formatVersion be null.

  5. Fetch request with useParallelQueue set to true, and processResponseConsumeBody set to the following steps given a response response and null, failure, or a byte sequence responseBody:

    1. If validate fetching response with response, responseBody and "application/json" returns false, set signals to failure and return.

    2. Let headers be response’s header list.

    3. Set dataVersion to the result of getting a structured field value given `Data-Version` and "item" from headers.

    4. If dataVersion is not null:

      1. If dataVersion is not an integer, or is less than 0 or more than 232−1, set signals to failure and return.

    5. If isBiddingSignal is true, then set formatVersion to the result of getting a structured field value given `X-fledge-bidding-signals-format-version` and "item" from headers.

    6. Set signals to the result of parsing JSON bytes to an Infra value responseBody.

  6. Wait for signals to be set.

  7. If signals is a parsing exception, or if signals is not an ordered map, return « null, null ».

  8. For each keyvalue of signals:

    1. Set signals[key] to the result of serializing an Infra value to a JSON string given value.

  9. If formatVersion is 2:

    1. If signals["keys"] does not exist, return « null, null ».

    2. Set signals to signals["keys"].

    3. If signals is not an ordered map, return « null, null ».

    4. TODO: handle priority vector.

  10. Return « signals, dataVersion ».

To encode trusted signals keys given an ordered set of strings keys:

  1. Let list be a new empty list.

  2. Let keysStr be the result of concatenating keys with separator set to ",".

  3. Append the result of UTF-8 percent-encoding keysStr using component percent-encode set to list.

    The Chrome implementation encodes 0x20 (SP) to U+002B (+), while UTF-8 percent-encoding encodes it to "%20".

  4. Return list.

To convert an ad size to a string given an ad size adSize.

  1. Let sizeList be an empty list.

  2. Let jsWidth be adSize’s width, converted to an ECMAScript value.

  3. Append ToString(jsWidth) to sizeList.

  4. Append adSize’s width to sizeList.

  5. Append adSize’s width units to sizeList.

  6. Append "," to sizeList.

  7. Let jsHeight be adSize’s height, converted to an ECMAScript value.

  8. Append ToString(jsHeight) to sizeList.

  9. Append adSize’s height units to sizeList.

  10. Return the result of concatenating sizeList.

To calculate the ad slot size query param given an interest group ig and auction config config:

  1. Switch on ig’s trusted bidding signals slot size mode:

    "none"
    1. Return "".

    "slot-size"
    1. If config’s requested size is null, then return "".

    2. Otherwise:

      1. Let adSizeString the result of running convert an ad size to a string on config’s requested size.

      2. Return the result of concatenating « "&slotSize=", adSizeString ».

    "all-slots-requested-sizes"
    1. If config’s all slots requested sizes is null, then return "".

    2. Let allSizesList be a new list or strings.

    3. For each adSize in config’s all slots requested sizes:

      1. Let adSizeString the result of running convert an ad size to a string on adSize.

      2. Append adSizeString to allSizesList.

    4. Let allSizes be the result of concatenating allSizesList, with "," as a separator.

    5. Return the result of concatenating « "&allSlotsRequestedSizes=", allSizes ».

To build trusted bidding signals url given a URL signalsUrl, an ordered set of strings keys, an ordered set of strings igNames, an unsigned short-or-null experimentGroupId, an origin topLevelOrigin, and a string slotSizeQueryParam:

  1. Let queryParamsList be a new empty list.

    Note: These steps create a query of the form "&<name>=<values in comma-delimited list>". E.g., "hostname=publisher1.com&keys=key1,key2&interestGroupNames=ad+platform,name2&experimentGroupId=1234".

    These steps don’t use the application/x-www-form-urlencoded serializer to construct the query string because it repeats a key if it has multiple values instead of a comma-demilited list (e.g., "keys=key1&keys=key2", instead of "keys=key1,key2"), and it also uses a different percent encode set from the Chrome implementation.

  2. Append "hostname=" to queryParamsList.

  3. Append the result of UTF-8 percent-encoding the serialized topLevelOrigin using component percent-encode set to queryParamsList.

  4. If keys is not empty:

    1. Append "&keys=" to queryParamsList.

    2. Extend queryParamsList with the result of encode trusted signals keys with keys.

  5. If igNames is not empty:

    1. Append "&interestGroupNames=" to queryParamsList.

    2. Extend queryParamsList with the result of encode trusted signals keys with igNames.

  6. If experimentGroupId is not null:

    1. Append "&experimentGroupId=" to queryParamsList.

    2. Append serialized experimentGroupId to queryParamsList.

  7. Append slotSizeQueryParam to queryParamsList.

  8. Let fullSignalsUrl be signalsUrl.

  9. Set fullSignalsUrl’s query to the result of concatenating queryParamsList.

  10. return fullSignalsUrl.

To build trusted scoring signals url given a URL signalsUrl, a list of strings renderURLs, an ordered set of strings adComponentRenderURLs, an unsigned short experimentGroupId, and an origin topLevelOrigin:

Note: When trusted scoring signals fetches are not batched, renderURLs’s size is 1.

  1. Let queryParamsList be a new empty list.

  2. Append "hostname=" to queryParamsList.

  3. Append the result of UTF-8 percent-encoding topLevelOrigin using component percent-encode set to queryParamsList.

  4. If renderURLs is not empty:

    1. Append "&renderURLs=" to queryParamsList.

    2. Extend queryParamsList with the result of encode trusted signals keys with renderURLs.

  5. If adComponentRenderURLs is not empty:

    1. Append "&adComponentRenderURLs=" to queryParamsList.

    2. Extend queryParamsList with the result of encode trusted signals keys with adComponentRenderURLs.

  6. If experimentGroupId is not null:

    1. Append "&experimentGroupId=" to queryParamsList.

    2. Append serialized experimentGroupId to queryParamsList.

  7. Set signalsUrl’s query to the result of concatenating queryParamsList.

  8. return signalsUrl.

To send report given a URL url:
  1. Let request be a new request with the following properties:

    URL

    url

    client

    null

    mode

    "no-cors"

    referrer

    "no-referrer"

    credentials mode

    "omit"

    redirect mode

    "error"

    Stop using "no-cors" mode where possible (WICG/turtledove#667).

  2. Fetch request with useParallelQueue set to true.

To get direct from seller signals given an origin seller, a string-or-null adSlot, and a map capturedAuctionHeaders:
  1. If adSlot is not a string, then return null.

  2. Let directFromSellerSignals be null.

  3. Let directFromSellerSignalsKey be a new direct from seller signals key with its seller set to seller, and ad slot set to adSlot.

  4. If capturedAuctionHeaders[directFromSellerSignalsKey] exists:

    1. Set directFromSellerSignals to capturedAuctionHeaders[directFromSellerSignalsKey].

  5. Return directFromSellerSignals.

To get direct from seller signals for a seller given a direct from seller signals-or-null directFromSellerSignals:
  1. Let directFromSellerSignalsForSeller be a new DirectFromSellerSignalsForSeller.

  2. If directFromSellerSignals is null, then return directFromSellerSignalsForSeller.

  3. Set directFromSellerSignalsForSeller["auctionSignals"] to the result of running parse a JSON string to an Infra value given directFromSellerSignals’s auction signals.

  4. Set directFromSellerSignalsForSeller["sellerSignals"] to the result of running parse a JSON string to an Infra value given directFromSellerSignals’s seller signals.

  5. Return directFromSellerSignalsForSeller.

To get direct from seller signals for a buyer given a direct from seller signals-or-null directFromSellerSignals, and an origin owner:
  1. Let directFromSellerSignalsForBuyer be a new DirectFromSellerSignalsForBuyer.

  2. If directFromSellerSignals is null, then return directFromSellerSignalsForBuyer.

  3. Set directFromSellerSignalsForBuyer["auctionSignals"] to the result of running parse a JSON string to an Infra value given directFromSellerSignals’s auction signals.

  4. If directFromSellerSignals’s per buyer signals[owner] exists:

    1. Set directFromSellerSignalsForBuyer["perBuyerSignals"] to the result of running parse a JSON string to an Infra value given directFromSellerSignals’s per buyer signals[owner].

  5. Return directFromSellerSignalsForBuyer.

To report result given a leading bid info leadingBidInfo, a direct from seller signals-or-null directFromSellerSignals, an auction config-or-null winningComponentConfig, and a global object global:
  1. Let config be leadingBidInfo’s auction config.

  2. Let bidCurrency be null.

  3. If winningComponentConfig is not null:

    1. Assert that leadingBidInfo’s component seller is not null.

    2. Set bidCurrency to winningComponentConfig’s seller currency.

    3. If bidCurrency is null, then set bidCurrency to the result of looking up per-buyer currency with config and leadingBidInfo’s component seller.

  4. Otherwise, set bidCurrency to the result of looking up per-buyer currency with config and leadingBidInfo’s leading bid's interest group's owner.

  5. Let winner be leadingBidInfo’s leading bid.

  6. Let sellerCurrency be leadingBidInfo’s auction config's seller currency.

  7. Let highestScoringOtherBid be leadingBidInfo’s highest scoring other bid's bid in seller currency (or 0 if encountered a null).

  8. If sellerCurrency is null, then set highestScoringOtherBid to leadingBidInfo’s highest scoring other bid's bid's value (or 0 if encountered a null).

  9. Let bid be winner’s bid's value.

  10. Let modifiedBid be null.

  11. If winner’s modified bid is not null:

    1. If leadingBidInfo’s component seller is not null, then set bid to winner’s modified bid.

    2. Otherwise, set modifiedBid to winner’s modified bid.

  12. Let browserSignals be a ReportResultBrowserSignals with the following fields:

    topWindowHostname
    The result of running the host serializer on global’s top-level origin's host.
    interestGroupOwner
    Serialized winner’s interest group's owner.
    renderURL
    Serialized winner’s ad descriptor's url
    bid
    Stochastically rounded bid
    bidCurrency
    The result of serializing a currency tag with bidCurrency
    highestScoringOtherBid
    highestScoringOtherBid
    highestScoringOtherBidCurrency
    sellerCurrency if it is not null, "???" otherwise
    topLevelSeller
    leadingBidInfo’s top level seller if it is not null, undefined otherwise
    componentSeller
    leadingBidInfo’s component seller if it is not null, undefined otherwise
    desirability
    Stochastically rounded leadingBidInfo’s top score
    topLevelSellerSignals
    leadingBidInfo’s top level seller signals if it is not null, undefined otherwise
    modifiedBid
    Stochastically rounded modifiedBid if it is not null, undefined otherwise
    dataVersion
    leadingBidInfo’s scoring data version if it is not null, undefined otherwise
  13. Let igAd be the interest group ad from winner’s interest group's ads whose render url is winner’s ad descriptor's url.

  14. If igAd’s buyer and seller reporting ID exists and the result of query reporting ID k-anonymity count given winner’s interest group and igAd is true, then set browserSignals["buyerAndSellerReportingId"] to igAd’s buyer and seller reporting ID.

  15. Let sellerReportingScript be the result of fetching script with config’s decision logic url.

  16. Let « sellerSignals, reportUrl, reportingBeaconMap, ignored » be the result of evaluating a reporting script with sellerReportingScript, "reportResult", config’s config idl's reportingTimeout, and « config’s config idl, browserSignals, directFromSellerSignals ».

  17. Let reportingResult be a reporting result with the following items:

    report url

    reportUrl

    reporting beacon map

    reportingBeaconMap

  18. If leadingBidInfo’s top level seller is null (i.e., if we are reporting for a component seller), set leadingBidInfo’s component seller reporting result to reportingResult.

  19. Otherwise, set leadingBidInfo’s seller reporting result to reportingResult.

  20. Remove browserSignals["desirability"].

  21. Remove browserSignals["modifiedBid"].

  22. Remove browserSignals["topLevelSellerSignals"].

  23. Remove browserSignals["dataVersion"].

    Note: Remove fields specific to ReportResultBrowserSignals which only sellers can learn about, so that they are not passed to "reportWin()".

  24. Return « sellerSignals, browserSignals ».

To report win given a leading bid info leadingBidInfo, a string sellerSignals, a ReportingBrowserSignals browserSignals, and a direct from seller signals-or-null directFromSellerSignals:
  1. Let config be leadingBidInfo’s auction config.

  2. Let winner be leadingBidInfo’s leading bid.

  3. Let perBuyerSignals be config’s per buyer signals.

  4. Let buyer be winner’s interest group's owner.

  5. Let perBuyerSignalsForBuyer be perBuyerSignals[buyer] if that member exists, and null otherwise.

  6. Let reportWinBrowserSignals be a ReportWinBrowserSignals with the members that are declared on ReportingBrowserSignals initialized to their values in browserSignals.

  7. Add the following fields to reportWinBrowserSignals:

    dataVersion
    leadingBidInfo’s bidding data version if it is not null, undefined otherwise.
    adCost
    Rounded winner’s ad cost
    seller
    Serialized config’s seller
    madeHighestScoringOtherBid
    Set to true if leadingBidInfo’s highest scoring other bid owner is not null, and buyer is same origin with leadingBidInfo’s highest scoring other bid owner, false otherwise
    modelingSignals
    winner’s modeling signals if it is not null, undefined otherwise (TODO: noise and bucket this signal)
  8. Let igAd be the interest group ad from winner’s interest group's ads whose render url is winner’s ad descriptor's url.

  9. If igAd’s buyer and seller reporting ID does not exist and the result of query reporting ID k-anonymity count given winner’s interest group and igAd is true:

    1. If igAd’s buyer reporting ID exists, set reportWinBrowserSignals["buyerReportingId"] to igAd’s buyer reporting ID.

    2. Otherwise, Set reportWinBrowserSignals["interestGroupName"] to winner’s interest group name.

  10. Let buyerReportingScript be the result of fetching script with winner’s interest group's bidding url.

  11. Let reportFunctionName be "reportWin".

  12. If winner’s provided as additional bid is true:

    1. Set reportFunctionName be "reportAdditionalBidWin".

  13. Let « ignored, resultUrl, reportingBeaconMap, reportingMacroMap » be the result of evaluating a reporting script with buyerReportingScript, "reportWin", leadingBidInfo’s auction config's config idl's reportingTimeout, and « leadingBidInfo’s auction config's config idl's auctionSignals, perBuyerSignalsForBuyer, sellerSignals, reportWinBrowserSignals, directFromSellerSignals ».

  14. Set leadingBidInfo’s buyer reporting result to a reporting result with the following items:

    report url

    resultUrl

    reporting beacon map

    reportingBeaconMap

    reporting macro map

    reportingMacroMap

5. Reporting

5.1. forDebuggingOnly

This first introductory paragraph is non-normative.

"generateBid()" and "scoreAd()" can call forDebuggingOnly's reportAdAuctionWin(url) and reportAdAuctionLoss(url) methods for event-level forDebuggingOnly reports for winning and losing bids.

To collect a single forDebuggingOnly report given a URL reportUrl, an origin invokingOrigin, and a list debugReportUrls:

Note: While the browser is experimenting with third party cookie deprecation (before they have been fully removed), the forDebuggingOnly reporting APIs supply temporary labels indicating when a particular instance would have been downsampled instead of using the following steps to downsample it.

  1. If reportUrl is null, or the result of running is debugging only in cooldown or lockout with invokingOrigin is true, then return.

  2. If the result of running sample a debug report with invokingOrigin is true, then append reportUrl to debugReportUrls.

To collect forDebuggingOnly reports given a list of bid debug reporting info bidDebugReportInfoList, origin seller, and leading bid info-or-null winnerInfo:
  1. Let auctionReportInfo be a new auction report info.

  2. Let winningBid be winnerInfo’s leading bid if winnerInfo is not null, null otherwise.

  3. For each bidDebugReportInfo of bidDebugReportInfoList:

    1. If winningBid is not null and bidDebugReportInfo’s id is winningBid’s id:

      1. Assert that winningBid’s id is not null.

      2. Collect a single forDebuggingOnly report with bidDebugReportInfo’s bidder debug win report url, bidDebugReportInfo’s interest group owner, and auctionReportInfo’s debug win report urls.

      3. If bidDebugReportInfo’s component seller is null:

        1. Collect a single forDebuggingOnly report with bidDebugReportInfo’s seller debug win report url, seller, and auctionReportInfo’s debug win report urls.

      4. Otherwise:

        1. Collect a single forDebuggingOnly report with bidDebugReportInfo’s seller debug win report url, bidDebugReportInfo’s component seller, auctionReportInfo’s debug win report urls.

        2. Collect a single forDebuggingOnly report with bidDebugReportInfo’s top level seller debug win report url, seller, and auctionReportInfo’s debug win report urls.

    2. Otherwise:

      1. Collect a single forDebuggingOnly report with bidDebugReportInfo’s bidder debug loss report url, bidDebugReportInfo’s interest group owner, and auctionReportInfo’s debug loss report urls.

      2. If bidDebugReportInfo’s component seller is null:

        1. Collect a single forDebuggingOnly report with bidDebugReportInfo’s seller debug loss report url, seller, and auctionReportInfo’s debug loss report urls.

      3. Otherwise:

        1. Collect a single forDebuggingOnly report with bidDebugReportInfo’s seller debug loss report url, bidDebugReportInfo’s component seller, auctionReportInfo’s debug loss report urls.

        2. Collect a single forDebuggingOnly report with bidDebugReportInfo’s top level seller debug loss report url, seller, and auctionReportInfo’s debug loss report urls.

  4. Return auctionReportInfo.

To register a bid for forDebuggingOnly reports given a generated bid-or-null generatedBid, bid debug reporting info bidDebugReportInfo, a list of bid debug reporting info bidDebugReportInfoList:
  1. If generatedBid is not null:

    1. Set generatedBid’s id to bidDebugReportInfoList’s size.

    2. Set bidDebugReportInfo’s id to bidDebugReportInfoList’s size

  2. Append bidDebugReportInfo to bidDebugReportInfoList.

Instead of inserting to bidDebugReportInfoList in each component auction that runs in parallel, create a structure InterestGroupAuction that holds data for each auction separately (WICG/turtledove#1021).

5.1.1. Downsampling

This first introductory paragraph is non-normative.

Implementations may define their own values for the below constants based on their privacy goal, however we supply the below values as a starting point, inspired by what the initial implementation of this specification uses:

Note: More details of how these numbers are determined can be found in comments here: (WICG/turtledove#667).

The design of downsampling forDebuggingOnly reports has three main goals:

The user agent has a debug report lockout until, which is null or a moment, and a debug report cooldown, which is null or a map whose keys are origins and values are moments at which the cool down for the origin key expires.

To is debugging only in cooldown or lockout given an origin origin:
  1. If user agent's debug report lockout until is not null, and current wall time is less than user agent's debug report lockout until, return true.

  2. If user agent's debug report cooldown is null, then return false.

  3. If user agent's debug report cooldown[origin] exists and current wall time is less than user agent's debug report cooldown[origin], then return true.

  4. Return false.

To sample a debug report given an origin origin:
  1. Let canSendAfterSampled be false.

  2. Let sampleRand be a random long, 0 ≤ sampleRand < 1000, so each possible long would be chosen with a probability equal to sampling rate.

  3. If sampleRand is 0:

    1. Set canSendAfterSampled to true.

    2. Set user agent's debug report lockout until to current wall time plus lockout period.

  4. Let cooldownRand be a random long ≥ 0 and < 10, which corresponds to

    long cooldown rate.

  5. Let cooldownPeriod be long cooldown period if cooldownRand is 0, short cooldown period otherwise.

  6. Set user agent's debug report cooldown[origin] to current wall time plus cooldownPeriod.

  7. Return canSendAfterSampled.

6. Additional Bids and Negative Targeting

6.1. createAuctionNonce()

This first introductory paragraph is non-normative.

navigator.createAuctionNonce() creates an auction nonce, a one-time version 4 UUID uniquely associated with a single call to navigator.runAdAuction(). For multi-seller auctions, this ID is uniquely associated with all componentAuctions. This nonce will need to be passed back in via a subsequent call to navigator.runAdAuction() via the AuctionAdConfig. This is currently only needed for auctions that use additional bids, for which the auction nonce will be included in each additional bid as a way of ensuring that those bids are only used in the auctions for which they were intended.

[SecureContext]
partial interface Navigator {
  Promise<DOMString> createAuctionNonce();
};
The createAuctionNonce() method steps are:
  1. Let p be a new promise.

  2. Run the following steps in parallel:

    1. Let nonce be the string representation of a version 4 UUID.

    Because we’re going in parallel:
    • There is no guarantee that the promise will be resolved before other tasks get queued on the main thread;

    • ...which gives browsers the freedom to generate this UUID in another process, and asynchronously send it back to the main thread at an arbitrary future time.

    1. Queue a global task on DOM manipulation task source, given this's relevant global object, to resolve p with nonce.

  3. Return p.

6.2. Additional Bids

This first introductory paragraph is non-normative.

In addition to bids generated by interest groups, sellers can enable buyers to introduce bids generated outside of the auction, which are called additional bids. Additional bids are commonly triggered using contextual signals. Buyers compute the additional bids, likely as part of a contextual auction. Buyers need to package up each additional bid using a new data structure that encapsulates all of the information needed for the additional bid to compete against other bids in a Protected Audience auction.

Each additional bid is expressed using the following JSON data structure:

const additionalBid = {
  "bid": {
    "ad": 'ad-metadata',
    "adCost": 2.99,
    "bid": 1.99,
    "bidCurrency": "USD",
    "render": "https://www.example-dsp.com/ad/123.jpg",
    "adComponents": [adComponent1, adComponent2],
    "allowComponentAuction": true,
    "modelingSignals": 123,
  },
  "interestGroup": {
    "owner": "https://www.example-dsp.com"
    "name": "campaign123",
    "biddingLogicURL": "https://www.example-dsp.com/bid_logic.js"
  },
  "negativeInterestGroups": {
    joiningOrigin: "https://www.example-advertiser.com",
    interestGroupNames: [
      "example_advertiser_negative_interest_group_a",
      "example_advertiser_negative_interest_group_b",
    ]
  },
  "auctionNonce": "12345678-90ab-cdef-fedcba09876543210",
  "seller": "https://www.example-ssp.com",
  "topLevelSeller": "https://www.another-ssp.com"
}
To validate and convert additional bids given an auction config auctionConfig, an auction config-or-null topLevelAuctionConfig, a negative target info negativeTargetInfo, and a global object global:
  1. Assert that these steps are running in parallel.

  2. Assert that auctionConfig’s auction nonce is not null.

  3. Let auctionNonce be the string representation of auctionConfig’s auction nonce.

  4. Let capturedAdditionalBidsHeaders be global’s associated Document’s node navigable’s traversable navigable’s captured additional bids headers.

  5. Let additionalBids be a new list of decoded additional bids.

  6. For each encodedSignedAdditionalBid of capturedAdditionalBidsHeaders[auctionNonce]:

    1. Let signedAdditionalBid be the result of running forgiving-base64 decode with encodedSignedAdditionalBid.

    2. If signedAdditionalBid is failure, then continue.

    3. Let additionalBid be the result of running parse a signed additional bid given signedAdditionalBid, auctionConfig, topLevelAuctionConfig, and negativeTargetInfo.

    4. If additionalBid is not null, then append additionalBid to additionalBids.

  7. Return additionalBids.

To parse a signed additional bid given a byte sequence signedAdditionalBid, an auction config auctionConfig, an auction config-or-null topLevelAuctionConfig, and a negative target info negativeTargetInfo:
  1. Assert that these steps are running in parallel.

  2. Let parsedSignedAdditionalBid be the result of running parse a JSON string to an infra value given signedAdditionalBid.

  3. Return null if any of the following conditions hold:

    • parsedSignedAdditionalBid is not a map;

    • parsedSignedAdditionalBid["bid"] does not exist, or is not a string;

    • parsedSignedAdditionalBid["signatures"] does not exist, or is not a list.

  4. Let signatures be a new list of signed additional bid signatures.

  5. Let decodeSignatureFailed be false.

  6. For each sig of parsedSignedAdditionalBid["signatures"]:

    1. Set decodeSignatureFailed to true and break if any of the following conditions hold:

    2. Let maybeKey be the result of running forgiving-base64 decode with sig["key"].

    3. Let maybeSignature be the result of running forgiving-base64 decode with sig["signature"].

    4. Set decodeSignatureFailed to true and break if any of the following conditions hold:

      • maybeKey is failure, or its length is not 32;

      • maybeSignature is failure, or its length is not 64;

    5. Let signature be a signed additional bid signatures, whose key is maybeKey, and signature is maybeSignature.

    6. Append signature to signatures.

  7. If decodeSignatureFailed is true, then return null.

  8. Let decodedAdditionalBid be the result of decode an additional bid json given parsedSignedAdditionalBid["bid"], auctionConfig and topLevelAuctionConfig.

  9. Return null if any of the following conditions hold:

  10. Let verifiedSignatureKeys be a new set of byte sequences.

  11. For each signature of signatures:

    1. Let isSignatureValid be the result of running verify signature’s signature on message parsedSignedAdditionalBid["bid"] using signature’s key, with 0 for Ed25519ctx.

    2. If isSignatureValid is true, then append signature’s key to verifiedSignatureKeys.

  12. If the result of checking whether negative targeted given decodedAdditionalBid, verifiedSignatureKeys and negativeTargetInfo is true, then return null.

  13. Return decodedAdditionalBid.

To decode an additional bid json given a string additionalBidJson, an auction config auctionConfig, and an auction config-or-null topLevelAuctionConfig:
  1. Assert that these steps are running in parallel.

  2. Let parsedAdditionalBid be the result of parse a JSON string to an infra value given additionalBidJson.

  3. If parsedAdditionalBid is not a map, then return failure.

  4. Let result be a new decoded additional bid.

  5. Return failure if any of the following conditions hold:

  6. If topLevelAuctionConfig is null:

    1. If parsedAdditionalBid["topLevelSeller"] exists, then return failure.

  7. Otherwise:

    1. If parsedAdditionalBid["topLevelSeller"] does not exist, then return failure.

    2. Let bidTopLevelSeller be the result of running the parse an https origin with parsedAdditionalBid["topLevelSeller"].

    3. If bidTopLevelSeller is failure, or bidTopLevelSeller is not same origin with topLevelAuctionConfig’s seller, then return failure.

  8. If parsedAdditionalBid["interestGroup"] does not exist, then return failure.

  9. Let igMap be parsedAdditionalBid["interestGroup"].

  10. Return failure if any the following conditions hold:

    • igMap is not a map;

    • igMap["name"] does not exist, or is not a string;

    • igMap["biddingLogicURL"] does not exist, or is not a string;

    • igMap["owner"] does not exist, or is not a string;

  11. Let igOwner be the result of running parse an https origin given igMap["owner"].

  12. Let igName be igMap["name"].

  13. Let igBiddingUrl be the result of running url parser on igMap["biddingLogicURL"].

  14. Return failure if any of the following conditions hold:

  15. Let ig be a new interest group with the following properties:

    owner

    igOwner

    name

    igName

    bidding url

    igBiddingUrl

  16. If parsedAdditionalBid["bid"] does not exist, or is not a map, return failure.

  17. Let bidMap be parsedAdditionalBid["bid"].

  18. If bidMap["render"] does not exist or is not a string, then return failure.

  19. Let renderUrl be the result of running URL parser on bidMap["render"].

  20. If renderUrl is failure, then return failure.

  21. Let ad be a new interest group ad whose render url is renderUrl.

  22. Set ig’s ads to « ad ».

  23. Let bidVal be bidMap["bid"] if it exists, otherwise return failure.

  24. If bidVal is not a double, or is less than or equal to 0, then return failure.

  25. Let adMetadata be "null".

  26. If bidMap["ad"] exists:

    1. Set adMetadata to the result of running serialize an Infra value to a JSON string with bidMap["ad"].

  27. Let bidCurrency be null.

  28. If bidMap["bidCurrency"] exists:

    1. If bidMap["bidCurrency"] is not a string, or the result of checking whether a string is a valid currency tag is failure, then return failure.

    2. Set bidCurrency to bidMap["bidCurrency"].

  29. Let adCost be null.

  30. If bidMap["adCost"] exists:

    1. If bidMap["adCost"] is not a double, then return failure.

    2. Set adCost to bidMap["adCost"].

  31. Let modelingSignals be null.

  32. If bidMap["modelingSignals"] exists:

    1. If bidMap["modelingSignals"] is not a double, then return failure.

    2. If bidMap["modelingSignals"] ≥ 0, and < 4096, then set modelingSignals to bidMap["modelingSignals"].

  33. Let adComponents be a new list of ad descriptors.

  34. If bidMap["adComponents"] exists:

    1. If bidMap["adComponents"] is not a list, then return failure.

    2. For each component of bidMap["adComponents"]:

      1. If component is not a string, then return failure.

      2. Let componentUrl be the result of running URL parser on component.

      3. If componentUrl is failure, then return failure.

      4. Let componentDescriptor be a new ad descriptor whose url is componentUrl.

      5. Append componentDescriptor to adComponents.

    3. Set ig’s ad components to adComponents.

  35. If parsedAdditionalBid["negativeInterestGroup"] exists:

    1. If parsedAdditionalBid["negativeInterestGroups"] exists, or parsedAdditionalBid["negativeInterestGroup"] is not a string, then return failure.

    2. Append parsedAdditionalBid["negativeInterestGroup"] to result’s negative target interest group names.

  36. If parsedAdditionalBid["negativeInterestGroups"] exists:

    1. Let multipleNegativeIg be parsedAdditionalBid["negativeInterestGroups"].

    2. Return failure if any of the following conditions hold:

      • multipleNegativeIg is not a map;

      • multipleNegativeIg["joiningOrigin"] does not exist, or is not a string;

      • multipleNegativeIg["interestGroupNames"] does not exist, or is not a list.

    3. Let joiningOrigin be the result of running parse an https origin with multipleNegativeIg["joiningOrigin"].

    4. If joiningOrigin is failure, then return failure.

    5. Set result’s negative target joining origin to joiningOrigin.

    6. For each igName of multipleNegativeIg["interestGroupNames"]:

      1. If igName is not a string, then return failure.

      2. Append igName to result’s negative target interest group names.

  37. Set result’s bid to a new generated bid with the following properties:

    bid

    A bid with currency whose value is bidVal, and currency is bidCurrency

    ad

    adMetadata

    ad descriptor

    An ad descriptor whose url is renderUrl

    ad component descriptors

    adComponents

    ad cost

    adCost

    modeling signals

    modelingSignals

    interest group

    ig

    bid ad

    A interest group ad whose render url is renderUrl, and metadata is adMetadata

    provided as additional bid

    true

  38. Return result.

A signed additional bid signature is a struct with the following items:

key

A byte sequence of length 32.

signature

A byte sequence of length 64.

A decoded additional bid is a struct with the following items:

bid

A generated bid. Fields analogous to those returned by generateBid().

negative target interest group names

A list of strings.

negative target joining origin

Null or an origin. Required if there is more than one entry in negative target interest group names.

Each traversable navigable has a captured additional bids headers, which is a map whose keys are strings for auction nonces, and whose values are list of strings for encoded additional bids.

6.3. Negative Targeting

This first introductory paragraph is non-normative.

In online ad auctions for ad space, it’s sometimes useful to prevent showing an ad to certain audiences, a concept known as negative targeting. To facilitate negative targeting in Protected Audience auctions, each additional bid is allowed to identify one or more negative interest groups. If the user has been joined to any of the identified negative interest groups, the additional bid is dropped; otherwise it participates in the auction, competing alongside bids created by calls to generateBid(). An additional bid that specifies no negative interest groups is always accepted into the auction.

To check whether negative targeted given an decoded additional bid additionalBid, a set of byte sequences verifiedSignatureKeys, and a negative target info negativeTargetInfo:
  1. Assert that these steps are running in parallel.

  2. Let negativeTargeted be false.

  3. Let additionalBidBuyer be additionalBid’s bid's interest group's owner.

  4. For each igName of additionalBid’s negative target interest group names:

    1. If negativeTargetInfo[(additionalBidBuyer, igName)] exists:

      1. Let (joiningOrigin, additionalBidKey) be negativeTargetInfo[(additionalBidBuyer, igName)].

      2. If verifiedSignatureKeys contains additionalBidKey:

        1. If joiningOrigin is not null:

          1. If joiningOrigin is not same origin with additionalBid’s negative target joining origin, then continue.

        2. Set negativeTargeted to true, and break.

Note: If the signature doesn’t verify successfully, the additional bid proceeds as if the negative interest group is not present. This ensures that only the owner of the negative interest group, who created the additionalBidKey, is allowed to negatively target the interest group, and that nobody else can learn whether the interest group set contains the interest group.

  1. Return negativeTargeted.

A negative target info is a map. Its keys are tuples consisting of an origin for owner and a string for name. Its values are tuples consisting of an origin for joining origin and a byte sequence for additional bid key.

6.3.1. Negative Interest Groups

This section is non-normative.

Though negative interest groups are joined using the same joinAdInterestGroup() API as regular interest groups, they remain distinct from one another. Only negative interest groups's additional bid key can be non-null, while only regular interest groups's ads can be non-null. Because the subset of fields used by a negative interest group cannot be meaningfully updated, a negative interest group's update url must be null, otherwise a TypeError will be thrown by joinAdInterestGroup() API.

Additional bids specify the negative interest groups they’re negatively targeting against using at most one of the following two fields in their JSON data structure:

If an additional bid needs to specify more than one negative interest groups, all of those negative interest groups must be joined from the same origin, and that origin must be identified ahead of time in the additional bid's joiningOrigin field. Any negative interest group that wasn’t joined from that identified origin is ignored for negative targeting.

Use negativeInterestGroup in additional bid’s JSON:

const additionalBid = {
  ...
  "negativeInterestGroup": "example_advertiser_negative_interest_group",
  ...
}

Use negativeInterestGroups in additional bid’s JSON:

const additionalBid = {
  ...
  "negativeInterestGroups": {
    joiningOrigin: "https://example-advertiser.com",
    interestGroupNames: [
      "example_advertiser_negative_interest_group_a",
      "example_advertiser_negative_interest_group_b",
    ]
  },
  ...
}

7. K-anonymity

Two goals of this specification rely on applying k-anonymity thresholds:

The browser enforces these k-anonymity requirements by maintaining counts of how many times each ad and ad component has been shown to users. These counts are maintained across users, so the counting must be done on a central k-anonymity server. This specification relies on two operations to query and increment the counts: query k-anonymity count and increment k-anonymity count.

The details of how the k-anonymity server is operated and accessed are implementation-defined but it should be done in a way that prevents the server operator from joining the identity of two query or increment requests. One way to help prevent this is by making accesses to the server go through an HTTP proxy that prevents the server from seeing the browsers' IP addresses.

The browser should choose a k-anonymity threshold, otherwise known as the value for "k", and a k-anonymity duration depending on the projected sizes of interest groups and the browser’s privacy goals. For example an implementation might choose to require a k-anonymity threshold of fifty users over a seven day period. The server will maintain the count over the chosen duration and compare the count to the chosen k-anonymity threshold when responding to query k-anonymity count.

To query k-anonymity count given a hashCode:
  1. If the k-anonymity server has recorded at least k-anonymity threshold users seeing hashCode over the last k-anonymity duration, return true. Otherwise return false.

  2. Return true if it is above the threshold, otherwise return false.

To query ad k-anonymity count given an interest group ig and a URL ad:
  1. Let keyString be the concatenation of the following strings separated with U+000A LF:

    1. "AdBid"

    2. the serialization of ig’s owner

    3. the serialization of ig’s bidding url

    4. the serialization of ad.

  2. Let keyHash be the SHA-256 hash of the ASCII encoding of keyString.

  3. Return the result of querying the k-anonymity count given keyHash.

To compute the key hash of reporting ID given an interest group ig and an interest group ad igAd:
  1. Let keyString be the concatenation of the following strings separated with U+000A (LF):

    1. "NameReport"

    2. the serialization of ig’s owner

    3. the serialization of ig’s bidding url

    4. the serialization of igAd’s render url

    5. If igAd’s buyer and seller reporting ID exists:

      1. "BuyerAndSellerReportingId"

      2. igAd’s buyer and seller reporting ID

    6. Otherwise, if igAd’s buyer reporting ID exists:

      1. "BuyerReportingId"

      2. igAd’s buyer reporting ID

    7. Otherwise:

      1. "IgName"

      2. ig’s name.

  2. Return the SHA-256 hash of the ASCII encoding of keyString.

To query component ad k-anonymity count given a URL ad:
  1. Let keyString be the concatenation of the following strings separated with U+000A LF:

    1. "ComponentBid"

    2. the serialization of ad.

  2. Let keyHash be the SHA-256 hash of the ASCII encoding of keyString.

  3. Return the result of querying the k-anonymity count given keyHash.

To query generated bid k-anonymity count given a generated bid bid:
  1. If query ad k-anonymity count given bid’s ad descriptor's url returns false, return false.

  2. If bid’s ad component descriptors is not null:

    1. For each adComponentDescriptor in bid’s ad component descriptors:

      1. If query component ad k-anonymity count given adComponentDescriptor’s url returns false, return false.

  3. Return true.

To query reporting ID k-anonymity count given an interest group ig and interest group ad igAd:
  1. Let keyHash be the result of computing the key hash of reporting ID given ig and igAd.

  2. Return the result of querying the k-anonymity count given keyHash.

To increment k-anonymity count given a hashCode:
  1. Ask the k-anonymity server to record that this user agent has seen hashCode.

To increment ad k-anonymity count given an interest group ig and a URL ad:
  1. Let keyString be the concatenation of the following strings separated with U+000A LF:

    1. "AdBid"

    2. the serialization of ig’s owner

    3. the serialization of ig’s bidding url

    4. the serialization of ad.

  2. Let keyHash be the SHA-256 hash of the ASCII encoding of keyString.

  3. Increment k-anonymity count given keyHash.

To increment component ad k-anonymity count given a URL ad:
  1. Let keyString be the concatenation of the following strings separated with U+000A LF:

    1. "ComponentBid"

    2. the serialization of ad.

  2. Let keyHash be the SHA-256 hash of the ASCII encoding of keyString.

  3. Increment k-anonymity count given keyHash.

To increment reporting ID k-anonymity count given an interest group ig and a URL ad:
  1. Let igAd be the interest group ad from ig’s ads whose render url is ad.

  2. Let keyHash be the result of computing the key hash of reporting ID given ig and igAd.

  3. Increment k-anonymity count given keyHash.

To increment a winning bid’s k-anonymity count given a generated bid winner:
  1. Increment ad k-anonymity count given winner’s interest group and winner’s ad descriptor's url.

  2. If winner’s ad component descriptors is not null:

    1. For each adComponentDescriptor in winner’s ad component descriptors:

      1. Increment component ad k-anonymity count given adComponentDescriptor’s url.

  3. Increment reporting ID k-anonymity count given winner’s interest group and winner’s ad descriptor's url.

8. Script Runners

This introduction sub-section is non-normative.

This specification defines a new type of script execution environment called a script runner. On the surface, these are similar to Worklets in that they too are used for running scripts independent of the main execution environment with a flexible implementation model.

However, some key differences from traditional Worklets motivate us to create a new kind of script execution environment. In particular, they:

8.1. Realm and agent

To create a new script runner agent, run these steps:
  1. Let signifier be a new unique internal value.

  2. Let candidateExecution be a new candidate execution.

  3. Return a new agent whose [[CanBlock]] is false, [[Signifier]] is signifier, [[CandidateExecution]] is candidateExecution, and [[IsLockFree1]], [[IsLockFree2]], and [[LittleEndian]] are set at the implementation’s discretion.

Note: This algorithm is almost identical to [HTML]'s create an agent algorithm, with the exception that we do not give the returned agent a new event loop, since it does not process tasks within task sources in the usual way.

To obtain a script runner agent, run these steps:
  1. Let agentCluster be a new agent cluster.

  2. Let agent be the result of creating a new script runner agent.

  3. Add agent to agentCluster.

  4. Return agent.

To create a new script runner realm with a global type globalType, run these steps:
  1. Assert that these steps are running in parallel.

  2. Let agent be the result of obtaining a script runner agent given null, true, and false. Run the rest of these steps in agent.

    This exclusively creates a new agent cluster for a given script to run in, but we should make this work with execution mode somehow.

  3. Let realmExecutionContext be the result of creating a new realm given agent and the following customizations:

    • For the global object, create a new object of type globalType.

  4. Let realm be realmExecutionContext’s Realm component.

  5. Let global be realm’s global object, and run these steps:

    1. Perform !global.[[Delete]]("Date").

    2. If !global.[[HasProperty]]("Temporal") is true, then perform !global.[[Delete]]("Temporal").

    This is not the best way to perform such API neutering (see tc39/ecma262#1357), but at the moment it’s the way that host environments do this.

    Note: Removing time-referencing APIs from the global object is imperative for privacy, as a script might otherwise be able to more easily exfiltrate data by using more accurate time measurements.

  6. Return realm.

8.2. Script evaluation

Concretely, a script runner is a JavaScript execution environment instantiated with one of the following global objects:

To evaluate a bidding script given a string script, an interest group ig, a currency tag expectedCurrency, a GenerateBidInterestGroup igGenerateBid, a string-or-null auctionSignals, a string-or-null perBuyerSignals, an ordered map trustedBiddingSignals, a BiddingBrowserSignals browserSignals, a DirectFromSellerSignalsForBuyer directFromSellerSignalsForBuyer and an integer millisecond duration timeout:
  1. Let realm be the result of creating a new script runner realm given InterestGroupBiddingScriptRunnerGlobalScope.

  2. Let global be realm’s global object.

  3. Let settings be realm’s settings object.

    WICG/turtledove#676 needs to be fixed in order to get realm’s settings object.

  4. Set global’s group has ad components to true if ig’s ad components is not null, or false otherwise.

  5. Set global’s expected currency to expectedCurrency.

  6. Let isComponentAuction be true if browserSignals["topLevelSeller"] is not null, or false otherwise.

  7. Set global’s is component auction to isComponentAuction.

  8. Set global’s interest group to ig.

  9. Let igJS be the result of converting to ECMAScript values given igGenerateBid.

  10. Let auctionSignalsJS be the result of parsing a JSON string to a JavaScript value given auctionSignals if auctionSignals is not null, otherwise undefined.

  11. Let perBuyerSignalsJS be the result of parsing a JSON string to a JavaScript value given perBuyerSignals if perBuyerSignals is not null, otherwise undefined.

  12. Let trustedBiddingSignalsJS be trustedBiddingSignals converted to ECMAScript values.

  13. Let browserSignalsJS be browserSignals converted to ECMAScript values.

  14. Let directFromSellerSignalsJs be directFromSellerSignalsForBuyer converted to ECMAScript values.

  15. Let startTime be settings’s current monotonic time.

  16. Let result be the result of evaluating a script with realm, script, "generateBid", « igJS, auctionSignalsJS, perBuyerSignalsJS, trustedBiddingSignalsJS, browserSignalsJS, directFromSellerSignalsJs », and timeout.

  17. Let duration be settings’s current monotonic time minus startTime in milliseconds.

  18. If global’s priority is not null and not failure:

    1. Set ig’s priority to global’s priority.

    2. Replace the interest group that has ig’s owner and name in the user agent's interest group set with ig.

  19. If global’s priority signals is not empty:

    1. For each kv of global’s priority signals:

      1. If v is null, remove ig’s priority signals overrides[k].

      2. Otherwise, set ig’s priority signals overrides[k] to v.

    2. Replace the interest group that has ig’s owner and name in the user agent's interest group set with ig.

  20. Let generatedBid be global’s bid.

  21. If result is a normal completion:

    1. Let generatedBidIDL be the result of converting result’s [[Value]] to a GenerateBidOutput.

    2. If no exception was thrown in the previous step:

      1. Let bidOutput be the result of converting GenerateBidOutput to generated bid with generatedBidIDL, ig, expectedCurrency, isComponentAuction, and global’s group has ad components.

      2. If bidOutput is not failure, then set generatedBid to bidOutput.

  22. Let bidDebugReportInfo be a new bid debug reporting info.

  23. Set bidDebugReportInfo’s interest group owner to ig’s owner

  24. Let debugLossReportUrl be global’s debug loss report url if it’s not failure, null otherwise.

  25. Set bidDebugReportInfo’s bidder debug loss report url to debugLossReportUrl.

  26. If generatedBid is a generated bid and generatedBid’s bid's value ≤ 0, then set generatedBid to null.

  27. If generatedBid is a generated bid:

    1. Let debugWinReportUrl be global’s debug win report url if it’s not failure, null otherwise.

    2. Set bidDebugReportInfo’s bidder debug win report url to debugWinReportUrl.

    3. Set generatedBid’s bid duration to duration, interest group to ig.

  28. Return « generatedBid, bidDebugReportInfo ».

To evaluate a scoring script given a string script, a string adMetadata, a double bidValue, an AuctionAdConfig auctionConfigIDL, an ordered map trustedScoringSignals, a ScoringBrowserSignals browserSignals, a DirectFromSellerSignalsForSeller directFromSellerSignalsForSeller, and an integer millisecond duration timeout:
  1. Let realm be the result of creating a new script runner realm given InterestGroupScoringScriptRunnerGlobalScope.

  2. Let browserSignalsJS be browserSignals converted to ECMAScript values.

  3. Let auctionConfigJS be auctionConfigIDL converted to ECMAScript values.

  4. Let trustedScoringSignalsJS be trustedScoringSignals converted to ECMAScript values.

  5. Let directFromSellerSignalsJs be directFromSellerSignalsForSeller converted to ECMAScript values.

  6. Let scoreAdResult be the result of evaluating a script with realm, script, "scoreAd", «adMetadata, bidValue, auctionConfigJS, trustedScoringSignalsJS, browserSignalsJS, directFromSellerSignalsJs», and timeout.

  7. Let debugWinReportUrl be global’s debug win report url if it’s not failure, null otherwise.

  8. Let debugLossReportUrl be global’s debug loss report url if it’s not failure, null otherwise.

  9. Return « scoreAdResult, debugWinReportUrl, debugLossReportUrl ».

To evaluate a reporting script given a string script, a string functionName, an integer millisecond duration timeout, and a list of arguments arguments:
  1. Let realm be the result of creating a new script runner realm given InterestGroupReportingScriptRunnerGlobalScope.

  2. Let global be realm’s global object.

  3. Let argumentsJS be the result of converting arguments to an ECMAScript arguments list. If this throws an exception, return « "null", null, null, null ».

  4. Let result be the result of evaluating a script with realm, script, functionName, argumentsJS, and timeout.

  5. If result is an abrupt completion, return « "null", null, null, null ».

  6. Let resultJSON be "null".

  7. If functionName is "reportResult", then set resultJSON to the result of serializing a JavaScript value to a JSON string given result.

    Note: Consider a return value that can’t be converted to JSON a valid result, so if an exception was thrown in the previous step, keep resultJSON as "null".

  8. Let reportURL be global’s report url

  9. If reportURL is failure, set reportURL to null.

  10. Let macroMap be global’s reporting macro map if functionName is "reportWin" or "reportAdditionalBidWin", null otherwise.

  11. Return « resultJSON, reportURL, global’s reporting beacon map, macroMap ».

To evaluate a script with a realm realm, string script, string functionName, a list arguments, and an integer millisecond duration timeout, run these steps. They return a Completion Record, which is either an abrupt completion (in the case of a parse failure or execution error), or a normal completion populated with the ECMAScript language value result of invoking functionName.
  1. Assert that these steps are running in parallel.

  2. If timeout ≤ 0, immediately interrupt the execution and set finalCompletion to a new throw completion given null.

  3. Let global be realm’s global object, and run these steps in realm’s agent:

  4. Let result be ParseScript(script, realm, empty).

    Note: The resulting Script Record will have no [[HostDefined]] component, unlike traditional scripts on the web platform.

  5. If result is a list of errors, return Completion { [[Type]]: throw, [[Value]]: result, [[Target]]: empty }.

  6. Assert: result is a Script Record.

  7. Prepare to run script: Push realmExecutionContext onto the JavaScript execution context stack; it is now the running JavaScript execution context.

  8. Let evaluationStatus be the result of ScriptEvaluation(result).

  9. If evaluationStatus is an abrupt completion, jump to the step labeled return.

  10. Let F be Get(global, functionName). If that returns a throw completion, set finalCompletion to F and jump to the step labeled return.

  11. Set finalCompletion be Completion(Call(F, undefined, arguments)).

    In timeout milliseconds, if the invocation of Call has not completed, immediately interrupt the execution and set finalCompletion to a new throw completion given null.

  12. Return: at this point finalCompletion will be set to a Completion Record.

    1. Clean up after script: Assert realmExecutionContext is the running JavaScript execution context, and remove it from the JavaScript execution context stack.

    2. Return finalCompletion.

8.3. Global scopes

An additional requirement to the interest group script runner globals defined in this specification is that they must not expose any interfaces from other specifications whose own exposure set is the special value "*". The only interfaces that can be exposed inside of the globals defined in this specification are those that explicitly list the global names provided here.

[Exposed=InterestGroupScriptRunnerGlobalScope]
interface InterestGroupScriptRunnerGlobalScope {
};

[Exposed=InterestGroupBiddingAndScoringScriptRunnerGlobalScope]
interface ForDebuggingOnly {
  undefined reportAdAuctionWin(USVString url);
  undefined reportAdAuctionLoss(USVString url);
};

[Exposed=InterestGroupBiddingAndScoringScriptRunnerGlobalScope,
 Global=InterestGroupBiddingAndScoringScriptRunnerGlobalScope]
interface InterestGroupBiddingAndScoringScriptRunnerGlobalScope : InterestGroupScriptRunnerGlobalScope {

  readonly attribute ForDebuggingOnly forDebuggingOnly;
};

Each InterestGroupBiddingAndScoringScriptRunnerGlobalScope has an associated forDebuggingOnly, which is an ForDebuggingOnly instance created alongside the InterestGroupBiddingAndScoringScriptRunnerGlobalScope.

The forDebuggingOnly getter steps are:
  1. Return this's relevant global object's forDebuggingOnly.

Each InterestGroupBiddingAndScoringScriptRunnerGlobalScope has a

debug win report url

Null, failure, or a URL whose scheme is "https". Initially null.

debug loss report url

Null, failure, or a URL whose scheme is "https". Initially null.

The reportAdAuctionWin(url) method steps are:
  1. Let global be this's relevant global object.

  2. Let parsedUrl be the result of running the URL parser on url.

  3. If parsedUrl is failure, or parsedUrl’s scheme is not "https", then set global’s debug win report url to failure.

  4. Optionally, return.

    Note: This implementation-defined condition is intended to allow user agents to decline for a number of reasons, for example the parsedUrl’s site not being enrolled.

  5. Set global’s debug win report url to parsedUrl.

The reportAdAuctionLoss(url) method steps are:
  1. Let global be this's relevant global object.

  2. Let parsedUrl be the result of running the URL parser on url.

  3. If parsedUrl is failure, or parsedUrl’s scheme is not "https", then set global’s debug loss report url to failure.

  4. Optionally, return.

    Note: This implementation-defined condition is intended to allow user agents to decline for a number of reasons, for example the parsedUrl’s site not being enrolled.

  5. Set global’s debug loss report url to parsedUrl.

8.3.1. InterestGroupBiddingScriptRunnerGlobalScope

[Exposed=InterestGroupBiddingScriptRunnerGlobalScope,
 Global=(InterestGroupScriptRunnerGlobalScope,
         InterestGroupBiddingScriptRunnerGlobalScope)]
interface InterestGroupBiddingScriptRunnerGlobalScope
        : InterestGroupBiddingAndScoringScriptRunnerGlobalScope {
  boolean setBid(optional GenerateBidOutput generateBidOutput = {});
  undefined setPriority(double priority);
  undefined setPrioritySignalsOverride(DOMString key, optional double? priority);
};

dictionary AdRender {
  required DOMString url;
  DOMString width;
  DOMString height;
};

dictionary GenerateBidOutput {
  double bid = -1;
  DOMString bidCurrency;
  (DOMString or AdRender) render;
  any ad;
  sequence<(DOMString or AdRender)> adComponents;
  double adCost;
  unrestricted double modelingSignals;
  boolean allowComponentAuction = false;
};

Each InterestGroupBiddingScriptRunnerGlobalScope has a

bid

Null, or a generated bid, initially null.

priority

Null, failure, or a double, initially null.

priority signals

An ordered map whose keys are strings and whose values are double or null.

interest group

An interest group

expected currency

A currency tag

is component auction

A boolean

group has ad components

A boolean

To convert GenerateBidOutput to generated bid given a GenerateBidOutput generateBidOutput, an interest group ig, a currency tag expectedCurrency, a boolean isComponentAuction and a boolean groupHasAdComponents:

  1. Let bid be a new generated bid.

  2. If generateBidOutput["bid"] ≤ 0:

    1. Set bid’s bid to a bid with currency with value generateBidOutput["bid"] and currency null.

    2. Return bid.

  3. If generateBidOutput["render"] does not exist, return failure.

  4. If isComponentAuction is true, and generateBidOutput["allowComponentAuction"] is false, then return failure.

  5. Let bidCurrency be null.

  6. If generateBidOutput["bidCurrency"] is specified:

    1. If the result of checking whether a string is a valid currency tag on generateBidOutput["bidCurrency"] is true, then set bidCurrency to generateBidOutput["bidCurrency"], otherwise return failure.

  7. If the result of checking a currency tag with expectedCurrency and bidCurrency is false, return failure.

  8. Set bid’s bid to a bid with currency with value generateBidOutput["bid"] and currency bidCurrency.

  9. If generateBidOutput["ad"] exists:

    1. Let adJSON be the result of serializing a JavaScript value to a JSON string, given generateBidOutput["ad"].

    2. If adJSON is failure, return failure.

    3. Set bid’s ad to adJSON.

  10. Let adDescriptor be a new ad descriptor.

  11. If generateBidOutput["render"] is a DOMString:

    1. Let adUrl be the result of running the URL parser on generateBidOutput["render"].

    2. If adUrl is failure, return failure.

    3. Set adDescriptor’s url to adUrl.

  12. Otherwise:

    1. Set adDescriptor to the result of converting an ad render given generateBidOutput["render"].

    2. If adDescriptor is failure, return failure.

  13. Let bidAd be the result of finding matching ad given adDescriptor, ig, and false.

  14. If bidAd is null, return failure.

  15. Set bid’s ad descriptor to adDescriptor.

  16. Set bid’s bid ad to bidAd.

  17. If generateBidOutput["adComponents"] exists:

    1. Let adComponents be generateBidOutput["adComponents"].

    2. Return failure if any of the following conditions hold:

      • groupHasAdComponents is false;

      • adComponents’s size is greater than 40.

    3. Let adComponentDescriptors be a new list of ad descriptors.

    4. For component in adComponents:

      1. Let componentDescriptor be a new ad descriptor.

      2. If component is DOMString:

        1. Let componentUrl be the result of running the URL parser on component.

        2. If componentUrl is failure, return failure.

        3. Set componentDescriptor’s url to componentUrl.

      3. Otherwise:

        1. Set componentDescriptor to the result of converting an ad render given component.

        2. If componentDescriptor is failure, return failure.

      4. If finding matching ad given componentUrl, ig, and true returns null, return failure.

      5. Append componentDescriptor to adComponentDescriptors.

    5. Set bid’s ad component descriptors to adComponentDescriptors.

  18. If generateBidOutput["adCost"] exists, then set bid’s ad cost to generateBidOutput["adCost"].

  19. If generateBidOutput["modelingSignals"] exists:

    1. Let modelingSignals be generateBidOutput["modelingSignals"].

    2. If modelingSignals ≥ 0 and modelingSignals < 4096, then set bid’s modeling signals to the result of converting the ECMAScript value represented by modelingSignals to an unsigned short.

  20. Return bid.

To parse an AdRender dimension value given a string input:
  1. Let position be a position variable, initially pointing at the start of input.

  2. Strip leading and trailing ASCII whitespace from input.

  3. If input starts with "0" but is not "0" and does not start with "0.", then return null as the dimension and the empty string as the dimension unit.

  4. Collect a sequence of code points that are ASCII digits or U+002E (.), given position. Let that be dimensionString.

  5. If dimensionString is the empty string, then return null as the dimension and the empty string as the dimension unit.

  6. Let dimension be the result of parsing dimensionString using the rules for parsing floating-point number values.

  7. If dimension is an error, then return null as the dimension and the empty string as the dimension unit.

  8. Collect a sequence of code points that are ASCII lower alpha, given position. Let that be dimensionUnit.

  9. If position is not past the end of input, then return null as the dimension and the empty string as the dimension unit.

  10. If dimensionUnit is the empty string, then set dimensionUnit to "px".

  11. If dimensionUnit is not "px", "sh", or "sw", then return null as the dimension and the empty string as the dimension unit.

  12. Return dimension as the dimension and dimensionUnit as the dimension unit.

To convert an ad render given an AdRender adRender:
  1. Let adUrl be the result of running the URL parser on adRender["url"].

  2. If adUrl is failure, return failure.

  3. Let adDescriptor be a new ad descriptor.

  4. Set adDescriptor’s url to adUrl.

  5. If adRender["width"] exists:

    1. If adRender["height"] does not exist, return failure.

    2. Let width and widthUnit be the dimension and dimension unit that results from running parse an AdRender dimension value with adRender["width"], respectively.

    3. If width is null, return failure.

    4. Let height and heightUnit be the dimension and dimension unit that results from running parse an AdRender dimension value with adRender["height"], respectively.

    5. If height is null, return failure.

    6. Let adSize be a new ad size.

    7. Set adSize’s width to width, width units to widthUnit, height to height, height units to heightUnit.

    8. Set adDescriptor’s size to adSize.

  6. Return adDescriptor.

To find matching ad given an ad descriptor adDescriptor, an interest group ig, and a boolean isComponent:
  1. Let adUrl be adDescriptor’s url.

  2. If adUrl’s scheme is not "https", return null.

  3. TODO: Need to check size as well.

  4. If isComponent, for each ad in ig’s ad components:

    1. If ad’s render url equals adUrl, return ad.

  5. Otherwise, for each ad in ig’s ads:

    1. If ad’s render url equals adUrl, return ad.

  6. Return null.

The setBid(generateBidOutput) method steps are:
  1. Let global be this's relevant global object.

  2. Set global’s bid to null.

  3. Let ig be global’s interest group.

  4. Let expectedCurrency be global’s expected currency.

  5. Let bidToSet be the result of converting GenerateBidOutput to generated bid with generateBidOutput, ig, expectedCurrency, global’s is component auction, and global’s group has ad components.

  6. If bidToSet is failure, throw a TypeError.

  7. Set global’s bid to bidToSet.

The setPriority(priority) method steps are:
  1. Let global be this's relevant global object.

  2. If global’s priority is not null, then set global’s priority to failure, and throw a TypeError.

  3. Set global’s priority to priority.

The setPrioritySignalsOverride(key, priority) method steps are:
  1. Set this's relevant global object's priority signals[key] to priority.

8.3.2. InterestGroupScoringScriptRunnerGlobalScope

[Exposed=InterestGroupScoringScriptRunnerGlobalScope,
 Global=(InterestGroupScriptRunnerGlobalScope,
         InterestGroupScoringScriptRunnerGlobalScope)]
interface InterestGroupScoringScriptRunnerGlobalScope
        : InterestGroupBiddingAndScoringScriptRunnerGlobalScope {
};

8.3.3. InterestGroupReportingScriptRunnerGlobalScope

[Exposed=InterestGroupReportingScriptRunnerGlobalScope,
 Global=(InterestGroupScriptRunnerGlobalScope,
         InterestGroupReportingScriptRunnerGlobalScope)]
interface InterestGroupReportingScriptRunnerGlobalScope
        : InterestGroupScriptRunnerGlobalScope {
  undefined sendReportTo(DOMString url);
  undefined registerAdBeacon(record<DOMString, USVString> map);
  undefined registerAdMacro(DOMString name, USVString value);
};

Note: registerAdMacro(name, value) is only available in report win, but not report result.

Each InterestGroupReportingScriptRunnerGlobalScope has a

report url

Null, failure, or a URL whose scheme is "https". Initially null.

reporting beacon map

Null or an ordered map whose keys are strings and whose values are URLs whose schemes are "https". Initially null.

reporting macro map

Null or an ordered map whose keys are strings and whose values are strings. Initially null.

The sendReportTo(url) method steps are:
  1. Let global be this's relevant global object.

  2. If global’s report url is not null, then set global’s report url to failure, and throw a TypeError.

  3. Let parsedUrl be the result of running the URL parser on url.

  4. If parsedUrl is failure, or parsedUrl’s scheme is not "https", set global’s report url to failure, and throw a TypeError.

  5. Optionally, return.

    Note: This implementation-defined condition is intended to allow user agents to decline for a number of reasons, for example the parsedUrl’s site not being enrolled.

  6. Set global’s report url to parsedUrl.

The registerAdBeacon(map) method steps are:
  1. If this's relevant global object's reporting beacon map is not null, then Throw a TypeError.

  2. For each typeurl of map:

    1. If type starts with "reserved." and type does not match one of the automatic beacon event type values, throw a TypeError.

    2. Let parsedURL be the result of running URL parser on url.

    3. Throw a TypeError if any of the following conditions hold:

      • parsedURL is failure;

      • parsedURL’s scheme is not "https".

  3. Set this's relevant global object's reporting beacon map to map.

The registerAdMacro(name, value) method steps are:
  1. For each code unit c in name:

    1. Throw a TypeError if both of the following conditions hold:

  2. For each code unit c in value:

    1. Throw a TypeError if both of the following conditions hold:

  3. Set this's relevant global object's reporting macro map[name] to value.

9. Interest Group Updates

This first introductory paragraph is non-normative.

Interest groups have an update url field that allows updating the interest group definition stored on disk with information periodically retrieved from the update url. The interest group update steps are triggered during runAdAuction() and by calls to updateAdInterestGroups() API:

[SecureContext]
partial interface Navigator {
  undefined updateAdInterestGroups();
};

The updateAdInterestGroups() method steps are:

  1. In parallel, run interest group update with « relevant settings object's top-level origin »

To update interest groups given a list of origins owners:
  1. For each owner of owners:

    1. For each originalInterestGroup of the user agent's interest group set whose owner is owner and next update after is before the current wall time:

      Note: Implementations can consider loading only a portion of these interest groups at a time to avoid issuing too many requests at once.

      1. Let ig be a deep copy of originalInterestGroup.

      2. Let request be a new request with the following properties:

        URL

        ig’s update url

        header list

        «Accept: application/json»

        client

        null

        mode

        "no-cors"

        referrer

        "no-referrer"

        credentials mode

        "omit"

        redirect mode

        "error"

        One of the side-effects of a null client for this subresource request is it neuters all service worker interceptions, despite not having to set the service workers mode.

        Stop using "no-cors" mode where possible (WICG/turtledove#667).

      3. Let update be null.

      4. Fetch request with useParallelQueue set to true, and processResponseConsumeBody set to the following steps given a response response and null, failure, or a byte sequence responseBody:

        1. If validate fetching response with response, responseBody and "application/json" returns false, set update to failure and return.

        2. Set update to responseBody.

      5. Wait for update to be set.

      6. If update is failure, continue.

      7. Let parsedUpdate be the result of parsing JSON bytes to an Infra value, given update.

      8. If parsedUpdate is failure, continue.

      9. If parsedUpdate is not an ordered map, continue.

      10. If parsedUpdate["name"] exists and doesn’t match ig’s name, continue.

      11. If parsedUpdate["owner"] exists and doesn’t match ig’s owner, continue.

      12. For each keyvalue of parsedUpdate:

        1. Switch on key:

          "priority"
          1. If value is a double, set ig’s priority to value.

          2. Otherwise, jump to the step labeled Abort update.

          "enableBiddingSignalsPrioritization"
          1. If value is a boolean, set ig’s enable bidding signals prioritization to value.

          2. Otherwise, jump to the step labeled Abort update.

          "priorityVector"
          1. If value is null or an ordered map whose keys are strings and whose values are double, set ig’s priority vector to value.

          2. Otherwise, jump to the step labeled Abort update.

          "prioritySignalsOverrides"
          1. If value is an ordered map whose keys are strings and whose values are double or null:

            1. For each pvKeypvValue of value:

              1. If pvValue is null, remove ig’s priority signals overrides[pvKey].

              2. Otherwise, set ig’s priority signals overrides[pvKey] to pvValue.

          2. Otherwise, jump to the step labeled Abort update.

          "sellerCapabilities"
          1. If value is an ordered map whose keys are strings and whose values are lists of strings, for each sellerStringcapabilities of value:

            1. Let sellerCapabilities be a new set of seller capabilities.

            2. For each capabilityString of capabilities:

              1. If capabilityString is "interest-group-counts" or "latency-stats", then append capabilityString to sellerCapabilities.

                Note: For forward compatibility with new values, don’t throw.

            3. If sellerString is "*", then set ig’s all sellers capabilities to sellerCapabilities.

            4. Otherwise:

              1. If ig’s seller capabilities is null, then set ig’s seller capabilities to a new ordered map whose keys are origins and whose values are sets of seller capabilities.

              2. Let sellerUrl be the result of running the URL parser on sellerString.

              3. If sellerUrl is not failure:

                1. Let seller be sellerUrl’s origin.

                2. If ig’s seller capabilities does not contain seller, then set ig’s seller capabilities[seller] to sellerCapabilities.

          2. Otherwise, jump to the step labeled Abort update.

          "executionMode"
          1. If value is "compatibility", "frozen-context", or "group-by-origin", then set ig’s execution mode to value.

          2. Otherwise, set ig’s execution mode to "compatibility".

          "biddingLogicURL"
          "biddingWasmHelperURL"
          "updateURL"
          "trustedBiddingSignalsURL"
          1. For each groupMember and interestGroupField in the following table

            Group member Interest group field
            "biddingLogicURL" bidding url
            "biddingWasmHelperURL" bidding wasm helper url
            "updateURL" update url
            "trustedBiddingSignalsURL" trusted bidding signals url
            1. Let parsedURL be the result of running the URL parser on value.

            2. If key is not groupMember, continue.

            3. Jump to the step labeled Abort update if any of the following conditions hold:

            4. Set ig’s interestGroupField to parsedURL.

          "trustedBiddingSignalsKeys"
          1. If value is a list of strings, set ig’s trusted bidding signals keys to value.

          2. Otherwise, jump to the step labeled Abort update.

          "trustedBiddingSignalsSlotSizeMode"
          1. If value is one of "none", "slot-size", or "all-slots-requested-sizes", set ig’s trusted bidding signals slot size mode to value.

          2. Otherwise, set trusted bidding signals slot size mode to "none".

          "maxTrustedBiddingSignalsURLLength"
          1. If value is a Number:

            1. Let convertedValue be the result of converting value to a long.

            2. If convertedValue ≥ 0, then set ig’s max trusted bidding signals url length to convertedValue.

          2. Otherwise, jump to the step labeled Abort update.

          "userBiddingSignals"
          1. Set ig’s user bidding signals to the result of serialize an Infra value to JSON bytes given value.

          2. Otherwise, jump to the step labeled Abort update.

          Serializing an Infra value to JSON bytes expects to be called within a valid ES realm. See infra/625

          "ads"
          "adComponents"
          1. For each groupMember and interestGroupField in the following table

            Group member Interest group field
            "ads" ads
            "adComponents" ad components
            1. If key is not groupMember, continue.

            2. If value is not a list of AuctionAd, jump to the step labeled Abort update.

            3. Let igAds be a new list of interest group ads.

            4. For each ad of value:

              1. Let igAd be a new interest group ad.

              2. Let renderURL be the result of running the URL parser on ad["renderURL"].

              3. Jump to the step labeled Abort update if any of the following conditions hold:

              4. Set igAd’s render url to renderURL.

              5. If ad["metadata"] exists, then let igAd’s metadata be the result of serializing a JavaScript value to a JSON string, given ad["metadata"]. If this throws, jump to the step labeled Abort update.

              6. If groupMember is "ads":

                1. If ad["buyerReportingId"] exists then set igAd’s buyer reporting ID to it.

                2. If ad["buyerAndSellerReportingId"] exists then set igAd’s buyer and seller reporting ID to it.

              7. Append igAd to igAds.

            5. If igAds is not is empty:

              1. Set ig’s interestGroupField to igAds.

          "additionalBidKey"
          1. Let decodedKey be the result of running forgiving-base64 decode with value.

          2. Jump to the step labeled Abort update if any of the following conditions hold:

            • decodedKey is a failure;

            • decodedKey’s length is not 32;

          3. Set ig’s additional bid key to decodedKey.

      13. Jump to the step labeled Abort update if any of the following conditions hold:

      14. Set ig’s next update after to the current wall time plus 24 hours.

      15. Replace the interest group that has ig’s owner and name in the user agent's interest group set with ig.

      16. Abort update: We jump here if some part of the interest group update failed. Continue to the next interest group update.

10. Feature Detection

The queryFeatureSupport() method permits checking what functionality is available in the current implementation, in order to help deploy new features. The return values specified in this specification are for an implementation that fully implements it.

[SecureContext]
partial interface Navigator {
  [SameObject] readonly attribute ProtectedAudience protectedAudience;
};

[SecureContext, Exposed=Window]
interface ProtectedAudience {
  any queryFeatureSupport(DOMString feature);
};

The queryFeatureSupport(feature) method steps are:

  1. If feature is "adComponentsLimit", return 40.

  2. Return undefined.

11. Common Algorithms

The following algorithms are some helper algorithms used in this specification.

The estimated size of an interest group ig is the sum of:

  1. The length of the serialization of ig’s owner.

  2. The length of ig’s name.

  3. 8, which is the size of ig’s priority.

  4. 4, which is the size of ig’s execution mode.

    Note: Each of execution mode's value represents a long integer, so 4 bytes.

  5. 2, which is the size of ig’s enable bidding signals prioritization.

  6. If ig’s priority vector is not null, for each keyvalue of priority vector:

    1. The length of key.

    2. 8, which is the size of value.

  7. If ig’s priority signals overrides is not null, for each keyvalue of priority signals overrides:

    1. The length of key.

    2. 8, which is the size of value.

  8. If ig’s seller capabilities is not null, then for each sellercapabilities of ig’s seller capabilities:

    1. The length of the serialization of seller.

    2. 4, which is capabilities’s underlying number of enum bytes.

  9. The length of the serialization of ig’s bidding url, if the field is not null.

  10. The length of the serialization of ig’s bidding wasm helper url, if the field is not null.

  11. The length of the serialization of ig’s update url, if the field is not null.

  12. The length of the serialization of ig’s trusted bidding signals url, if the field is not null.

  13. 4, which is the size of ig’s trusted bidding signals slot size mode.

    Note: Each of trusted bidding signals slot size mode's value represents a long integer, so 4 bytes.

  14. For each key of ig’s trusted bidding signals keys:

    1. The length of key.

  15. If ig’s max trusted bidding signals url length is not null:

    1. 4, which is the size of ig’s max trusted bidding signals url length.

  16. The length of ig’s user bidding signals.

  17. If ig’s ads is not null, for each ad of it:

    1. The length of the serialization of ad’s render url.

    2. The length of ad’s metadata if the field is not null.

    3. The length of ad’s buyer reporting ID if the field is not null.

    4. The length of ad’s buyer and seller reporting ID if the field is not null.

    5. If ad’s allowed reporting origins is not null, for each origin of it:

      1. The length of the serialization of origin.

  18. If ig’s ad components is not null, for each ad of it:

    1. The length of the serialization of ad’s render url.

    2. The length of ad’s metadata if the field is not null.

  19. If ig’s additional bid key is not null:

    1. 32, which is its size (number of bytes).

To parse an https origin given a string input:
  1. Let url be the result of running the URL parser on input.

  2. If url is failure, or its scheme is not "https", then return failure.

  3. Return url’s origin.

To serialize a URL given a URL-or-null url:
  1. If url is null, then return undefined.

  2. Return the serialization of url.

To round a value given a double value:
  1. If value is not a valid floating-point number, return value.

  2. Let valueExp be value’s IEEE 754 biased exponent field minus 1023.

  3. Let normValue be value multiplied by 2(−1 × valueExp).

  4. If valueExp < −128:

    1. If value < 0, return −0.

    2. Otherwise, return 0.

  5. If valueExp > 127:

    1. If value < 0, return −∞.

    2. Otherwise, return ∞.

  6. Let precisionScaledValue be normValue multiplied by 256.

  7. Let noisyScaledValue be precisionScaledValue plus a random double value greater than or equal to 0 but less than 1.

  8. Let truncatedScaledValue be the largest integer not greater than noisyScaledValue.

  9. Return truncatedScaledValue multiplied by 2(valueExp − 8).

To serialize an integer, represent it as a string of the shortest possible decimal number.

This would ideally be replaced by a more descriptive algorithm in Infra. See infra/201

To get uuid from string given a string input:
  1. If input’s length is not 36, return an empty string.

  2. Let uuidStr be an empty string.

  3. For each i in the range from 1 to 36, inclusive:

    1. Let unit be input’s ith code unit.

    2. If « 8, 13, 18, 23 » contains i:

      1. If unit is not 0x002D (-), then return an empty string.

    3. Otherwise:

      1. If unit is not an ASCII lower hex digit, then return an empty string.

      2. Append unit to the end of uuidStr.

  4. Return ASCII encoded uuidStr.

12. Permissions Policy Integration

This specification defines two policy-controlled features identified by the strings "join-ad-interest-group", and "run-ad-auction". Their default allowlists are "*".

Issue #522 on GitHub: “Move "join-ad-interest-group" & "run-ad-auction" default allowlists to `self`”

Currently they're *.

To check interest group permissions given an origin ownerOrigin, an origin frameOrigin, and an enum joinOrLeave which is "join" or "leave":

  1. If ownerOrigin is same origin with frameOrigin, then return true.

  2. Let encodedFrameOrigin be the result of UTF-8 percent-encoding the serialized frameOrigin using component percent-encode set.

  3. Let permissionsUrl be a new URL with the following items:

    scheme

    ownerOrigin’s scheme

    host

    ownerOrigin’s host

    port

    ownerOrigin’s port

    path

    « ".well-known", "interest-group", "permissions" »

    query

    The result of concatenating « "origin=", encodedFrameOrigin »

  4. Let request be a new request with the following properties:

    URL

    permissionsUrl

    header list

    «Accept: application/json»

    client

    null

    origin

    frameOrigin

    mode

    "cors"

    referrer

    "no-referrer"

    credentials mode

    "omit"

    redirect mode

    "error"

    One of the side-effects of a null client for this subresource request is it neuters all service worker interceptions, despite not having to set the service workers mode.

  5. Let resource be null.

  6. Fetch request with useParallelQueue set to true, and processResponseConsumeBody set to the following steps given a response response and null, failure, or a byte sequence responseBody:

    1. If responseBody is null or failure, set resource to failure and return.

    2. Let headers be response’s header list.

    3. Let mimeType be the result of extracting a MIME type from headers.

    4. If mimeType is failure or is not a JSON MIME Type, set resource to failure and return.

    5. Set resource to responseBody.

  7. Wait for resource to be set.

  8. If resource is failure, then return false.

  9. Let permissions be the result of parsing JSON bytes to an Infra value with resource, returning false on failure.

  10. If permissions is not an ordered map, then return false.

  11. If joinOrLeave is "join" and permissions["joinAdInterestGroup"] exists, then return permissions["joinAdInterestGroup"].

  12. If joinOrLeave is "leave" and permissions["leaveAdInterestGroup"] exists, then return permissions["leaveAdInterestGroup"].

  13. Return false.

The browser may cache requests for permissionsUrl within a network partition.

In order to prevent leaking data, the browser must request permissionsUrl regardless of whether the user is a member of the ad interest group. This prevents a leak of the user’s ad interest group membership to the server.

13. Fetch Patch for Auction Headers

This section specifies a manner by which some data, including additional bids and direct from seller signals, may be provided to auctions such that the data is only used within their intended auction.

Any Document in a traversable navigable may run a Protected Audience auction (with navigator.runAdAuction()) whose script runners functions receive signal objects derived from JSON from an `Ad-Auction-Signals` header, or additional bids derived from an `Ad-Auction-Additional-Bid` header, captured by a fetch() call (using the adAuctionHeaders option) initiated by any other Document in the same traversable navigable, or from an iframe navigation request (using the adauctionheaders content attribute on the iframe element).

Modify [FETCH]'s Fetch § 2 Infrastructure to add a new section called "Per Traversable Navigable Structures", with the following content:

Each traversable navigable has a captured ad auction signals headers, which is a map whose keys are direct from seller signals keys and whose values are direct from seller signals.

NOTE: This is only captured during a request whose initiator type is "fetch", made with the adAuctionHeaders option set to true, or during an iframe navigation request with the adauctionheaders content attribute set to true, as described in the `Ad-Auction-Signals` header description.

Each traversable navigable has a captured ad auction additional bids headers, which is a map whose keys are auction nonces and whose values are strings.

NOTE: This is only captured during a request whose initiator type is "fetch", made with the adAuctionHeaders option set to true, or during an iframe navigation request with the adauctionheaders content attribute set to true, as described in the `Ad-Auction-Additional-Bid` header description.

Modify the definition of a request:

A request has an associated boolean capture-ad-auction-headers. Unless stated otherwise it is false.

Modify [FETCH]'s RequestInit dictionary to add an adAuctionHeaders attribute:
partial dictionary RequestInit {
  boolean adAuctionHeaders;
};
The following step will be added to the new Request (input, init) constructor steps, before step "Set this's request to request":
  1. If init["adAuctionHeaders"] exists, then set request’s capture-ad-auction-headers to it.

Modify the iframe element to add a adauctionheaders content attribute. The IDL attribute adAuctionHeaders reflects the adauctionheaders content attribute.
partial interface HTMLIFrameElement {
  [CEReactions] attribute boolean adAuctionHeaders;
};
The following step will be added to the create navigation params by fetching steps after step "Let request be a new request, with ...":
  1. If navigable’s container is an iframe element, and if it has a adauctionheaders content attribute, then set request’s capture-ad-auction-headers to true.

The following step will be added to the HTTP-network-or-cache fetch algorithm, before step "Modify httpRequest’s header list per HTTP. ...":
  1. If request's capture-ad-auction-headers is true, then set a structured field value given «`Sec-Ad-Auction-Fetch`, the boolean ?1» in httpRequest’s header list.

The following will be added to Fetch § 3 HTTP extensions:

13.1. The `Sec-Ad-Auction-Fetch` HTTP request header

The `Sec-Ad-Auction-Fetch` request header is an optional structured header with of type boolean. `Sec-Ad-Auction-Fetch` will only be set on a request whose initiator type is "fetch", made with the adAuctionHeaders option set to true, or on an iframe navigation request with the adauctionheaders content attribute set to true. If `Sec-Ad-Auction-Fetch` is equal to ?1, the user agent will remove any `Ad-Auction-Signals` or `Ad-Auction-Additional-Bid` from the returned response -- the `Ad-Auction-Signals` or `Ad-Auction-Additional-Bid` value will instead only be used in Protected Audiences auctions.

13.2. The `Ad-Auction-Signals` HTTP response header

The `Ad-Auction-Signals` response header provides value of a JSON array of dictionaries, each with an adSlot key. Protected Audience non-component, component, and top-level auctions may specify which signals to load by the adSlot key.

13.3. The `Ad-Auction-Additional-Bid` HTTP response header.

The `Ad-Auction-Additional-Bid` response header provides value of a string in the format of <auction nonce>:<base64-encoding of the signed additional bid>, which corresponds to a single additional bid. The response may include more than one additional bid by specifying multiple instances of the `Ad-Auction-Additional-Bid` response header.

The following steps will be added to the HTTP fetch algorithm, immediately under the step "If internalResponse’s status is a redirect status:"
  1. Delete "`Ad-Auction-Signals`" from response’s header list.

  2. Delete "`Ad-Auction-Additional-Bid`" from response’s header list.

The following step will be added to the HTTP fetch algorithm, before step "Return response.":
  1. If response is not null, response’s status is not a redirect status, fetchParams’s task destination is a global object that’s a Window object, and request’s capture-ad-auction-headers is true:

    1. Let navigable be fetchParams’s task destination's associated Document's node navigable's traversable navigable.

    2. Run update captured headers with navigable’s captured ad auction signals headers, navigable’s captured ad auction additional bids headers, response’s header list, and request’s URL's origin.

The following algorithm will be added to the Fetch § 4 Fetching section:

To update captured headers with a captured ad auction signals headers storedSignalsHeaders, captured ad auction additional bids headers storedAdditionalBidsHeaders, header list responseHeaders, and origin requestOrigin:

  1. Let adAuctionSignals be the result of getting `Ad-Auction-Signals` from responseHeaders.

  2. If adAuctionSignals is not null:

    1. Delete "`Ad-Auction-Signals`" from responseHeaders.

      NOTE: This step prevents the header value from being used outside the intended auctions —​that is, scripts making the fetch() request aren’t able to load the header value.

    2. Handle ad auction signals header value given adAuctionSignals, storedSignalsHeaders and requestOrigin.

  3. Let additionalBids be the result of getting, decoding, and splitting `Ad-Auction-Additional-Bid` from responseHeaders.

  4. If additionalBids is not null:

    1. Delete "`Ad-Auction-Additional-Bid`" from responseHeaders.

      NOTE: This step prevents the header value from being used outside the intended auctions —​that is, scripts making the fetch() request aren’t able to load the header value.

    2. For each bid of additionalBids:

      1. Let nonceAndAdditionalBid be the result of strictly splitting bid on U+003A (:).

      2. If nonceAndAdditionalBid’s size is not 2, then continue.

      3. Let nonce be nonceAndAdditionalBid[0].

      4. If nonce’s length is not 36, then continue.

      5. Set storedAdditionalBidsHeaders[nonce] to nonceAndAdditionalBid[1].

To handle ad auction signals header value given a byte sequence adAuctionSignals, captured ad auction signals headers storedSignalsHeaders, and origin requestOrigin:
  1. Let parsedSignals be the result of parsing JSON bytes to an Infra value, given adAuctionSignals.

  2. If parsedSignals is failure or not a list, return.

  3. Let headerAdSlots be a new ordered set.

  4. For each signal of parsedSignals:

    1. If signal is not an ordered map, continue.

    2. If signal["adSlot"] doesn’t exist, continue.

    3. If headerAdSlots contains signal["adSlot"], continue. Optionally, report a warning to the console with a diagnostic error message indicating that a duplicate `Ad-Auction-Signals` adSlot dictionary was ignored.

    4. Append signal["adSlot"] to headerAdSlots.

    5. Let signalsKey be a new direct from seller signals key, with its seller set to requestOrigin and its ad slot set to signal["adSlot"].

    6. Let processedSignals be a new direct from seller signals.

    7. Remove signal["adSlot"].

    8. For each keyvalue of signal:

      1. Switch on key:

        "sellerSignals"
        1. Set processedSignals’s seller signals to the result of serializing an Infra value to a JSON string, given value.

        "auctionSignals"
        1. Set processedSignals’s auction signals to the result of serializing an Infra value to a JSON string, given value.

        "perBuyerSignals"
        1. If value is not an ordered map, continue.

        2. For each buyerbuyerSignals of value:

          1. Let buyerOrigin be the result of parsing an https origin on buyer.

          2. If buyerOrigin is failure, continue.

          3. Let buyerSignalsString be the result of serializing an Infra value to a JSON string, given buyerSignals.

          4. Set processedSignals’s per buyer signals[buyerOrigin] to buyerSignalsString.

    9. Set storedSignalsHeaders[signalsKey] to processedSignals.

14. Structures

dictionary PreviousWin {
  required long long timeDelta;
  required DOMString adJSON;
};

dictionary BiddingBrowserSignals {
  required DOMString topWindowHostname;
  required USVString seller;
  required long joinCount;
  required long bidCount;
  required long recency;
  required long adComponentsLimit;

  USVString topLevelSeller;
  sequence<PreviousWin> prevWinsMs;
  object wasmHelper;
  unsigned long dataVersion;
  boolean forDebuggingOnlyInCooldownOrLockout = false;
};

dictionary ScoringBrowserSignals {
  required DOMString topWindowHostname;
  required USVString interestGroupOwner;
  required USVString renderURL;
  required unsigned long biddingDurationMsec;
  required DOMString bidCurrency;

  unsigned long dataVersion;
  sequence<USVString> adComponents;
  boolean forDebuggingOnlyInCooldownOrLockout = false;
};

Note: ScoringBrowserSignals's adComponents is undefined when ad component descriptors is null or an empty list. It cannot be an empty list.

dictionary ReportingBrowserSignals {
  required DOMString topWindowHostname;
  required USVString interestGroupOwner;
  required USVString renderURL;
  required double bid;
  required double highestScoringOtherBid;

  DOMString bidCurrency;
  DOMString highestScoringOtherBidCurrency;
  USVString topLevelSeller;
  USVString componentSeller;

  USVString buyerAndSellerReportingId;
};

ReportingBrowserSignals includes browser signals both reportResult() and reportWin() get.

topWindowHostname
Top-level origin's host
interestGroupOwner
The winning interest group's owner.
renderURL
The render URL returned by "generateBid()". It is k-anonymous
bid
Stochastically rounded winning bid. This is always in the bidder’s own currency
highestScoringOtherBid
The stochastically rounded value of the bid that got the second highest score, or 0 if it’s not available. 0 for top-level auctions with components
bidCurrency
The currency the bid is in
highestScoringOtherBidCurrency
The currency the highestScoringOtherBid is in
topLevelSeller
Copied from top level seller
componentSeller
Copied from component seller
buyerAndSellerReportingId
Set if the winning ad had a buyer and seller reporting ID set in its listing in the interest group, and that value was jointly k-anonymous combined with interest group owner, bidding script URL, and ad creative URL.
dictionary ReportResultBrowserSignals : ReportingBrowserSignals {
  required double desirability;

  DOMString topLevelSellerSignals;
  double modifiedBid;
  unsigned long dataVersion;
};
desirability
The stochastically rounded value of the score returned by "scoreAd()" for the winning bid
topLevelSellerSignals
Metadata returned by the top-level seller’s "reportResult()", as JSON
modifiedBid
The stochastically rounded value of the bid value returned by the component seller’s "scoreAd()" method
dataVersion
Set to the value of the `Data-Version` header from the trusted scoring signals server, if any.
dictionary ReportWinBrowserSignals : ReportingBrowserSignals {
  double adCost;
  USVString seller;
  boolean madeHighestScoringOtherBid;
  DOMString interestGroupName;
  DOMString buyerReportingId;
  unsigned short modelingSignals;
  unsigned long dataVersion;
  KAnonStatus kAnonStatus;
};

enum KAnonStatus { "passedAndEnforced", "passedNotEnforced", "belowThreshold", "notCalculated" };
adCost
Stochastically rounded winner’s ad cost.
seller
The origin of the seller running the ad auction
madeHighestScoringOtherBid
True if the interest group owner was the only bidder that made bids with the second highest score
buyerReportingId
Set if the winning ad had a buyer reporting ID but not a buyer and seller reporting ID set in its listing in the interest group, and that value was jointly k-anonymous combined with interest group owner, bidding script URL, and ad creative URL.
interestGroupName
Only set if the tuple of interest group owner, name, bidding script URL and ad creative URL

were jointly k-anonymous, and the winning ad had neither buyer and seller reporting ID nor buyer reporting ID set in its listing in the interest group.

modelingSignals
A 0-4095 integer (12-bits) passed to reportWin(), with noising
dataVersion
Only set if the Data-Version header was provided in the response headers from the trusted bidding signals server
kAnonStatus
Indicate the k-anonymity status of the ad with the following KAnonStatus enums:
  • passedAndEnforced: The ad was k-anonymous and k-anonymity was required to win the auction.

  • passedNotEnforced: The ad was k-anonymous though k-anonymity was not required to win the auction.

  • belowThreshold: The ad was not k-anonymous but k-anonymity was not required to win the auction.

  • notCalculated: The browser did not calculate the k-anonymity status of the ad, and k-anonymity was not required to win the auction.

From a long-term perspective, the status will always be set to passedAndEnforced after k-anonymity is enforced. However, as a temporary solution, current implementations may set kAnonStatus to one of the other three statuses to allow API users to assess the future impact of enforcing that ads are k-anonymous.

dictionary DirectFromSellerSignalsForBuyer {
  any auctionSignals = null;
  any perBuyerSignals = null;
};
dictionary DirectFromSellerSignalsForSeller {
  any auctionSignals = null;
  any sellerSignals = null;
};

14.1. Interest group

An interest group is a struct with the following items:

expiry

A moment at which the browser will forget about this interest group.

owner

An origin. Frames that join interest groups owned by owner must either be served from owner, or another origin delegated by owner (See checking interest group permissions for details). The scheme must be "https".

name

A string. The (owner, name) tuple is a key that uniquely defines each interest group.

priority

A double, initially 0.0. Used to select which interest groups participate in an auction when the number of interest groups are limited by perBuyerGroupLimits. See applying interest groups limits to prioritized list.

enable bidding signals prioritization

A boolean, initially false. Being true if the interest group’s priority should be calculated using vectors from bidding signals fetch.

priority vector

Null or an ordered map whose keys are strings and whose values are double. Its dot product with the perBuyerPrioritySignals will be used in place of priority, if set.

priority signals overrides

Null or an ordered map whose keys are strings and whose values are double. Overrides the AuctionAdConfig's corresponding priority signals.

seller capabilities

Null or an ordered map whose keys are origins and whose values are sets of seller capabilities. The seller capabilities this interest group grants to each seller.

all sellers capabilities

Null or a set of seller capabilities. The default seller capabilities granted to sellers not listed in seller capabilities.

execution mode

One of three possible values: "compatibility", "frozen-context", or "group-by-origin". Initially "compatibility". Each value reprensents a long integer. TODO: Define spec for these execution modes, link to it from here and explain these modes.

bidding url

Null or a URL. The URL to fetch the buyer’s JavaScript from.

When non-null, the bidding url's origin will always be same origin with owner.

bidding wasm helper url

Null or a URL. Lets the bidder provide computationally-expensive subroutines in WebAssembly, in addition to JavaScript, to be driven from the JavaScript function provided by bidding url.

When non-null, the bidding wasm helper url's origin will always be same origin with owner.

update url

Null or a URL. Provides a mechanism for the group’s owner to periodically update the attributes of the interest group. See § 9 Interest Group Updates. Must be null if additional bid key is not null.

When non-null, the update url's origin will always be same origin with owner.

trusted bidding signals url

Null or a URL. Provide a mechanism for making real-time data available for use at bidding time. See building trusted bidding signals url.

When non-null, the trusted bidding signals url's origin will always be same origin with owner.

trusted bidding signals keys

Null or a list of string. See building trusted bidding signals url.

trusted bidding signals slot size mode

"none", "slot-size" or "all-slots-requested-sizes". Initially "none". Each value reprensents a long integer. See calculate the ad slot size query param.

max trusted bidding signals url length

A long integer, initially 0. Indicates the maximum trusted bidding signals fetch url length for the interest group. 0 means no limit.

user bidding signals

Null or a string. Additional metadata that the owner can use during on-device bidding.

ads

Null or a list of interest group ad. Contains various ads that the interest group might show. Must be null if additional bid key is not null.

ad components

Null or a list of interest group ad. Contains various ad components (or "products") that can be used to construct ads composed of multiple pieces — a top-level ad template "container" which includes some slots that can be filled in with specific "products".

additional bid key

Null or a byte sequence of length 32. Must be null if ads or update url is not null. The Ed25519 public key (a 256-bit EdDSA public key) used to guarantee that this interest group, if used by an additional bid for a negative targeting, can only be used by its owner.

joining origin

An origin. The top level page origin from where the interest group was joined.

join counts

A list containing tuples of the day and per day join count. The day is calculated based on UTC time. The join count is a count of the number of times joinAdInterestGroup() was called for this interest group on the corresponding day.

join time

A moment at which the browser joined this interest group, updated upon each join and re-join.

bid counts

A list containing tuples of the day and per day bid count. The day is calculated based on UTC time. The bid count is a count of the number of times the bid calculated during runAdAuction() was greater than 0.

previous wins

A list of previous wins.

next update after

A moment at which the browser will permit updating this interest group. See interest group updates.

A regular interest group is an interest group whose additional bid key is null.

A negative interest group is an interest group whose additional bid key is not null.

An interest group ad is a struct with the following items:

render url

A URL. If this ad wins the auction, this URL (or a urn uuid that maps to this URL) will be returned by runAdAuction(). This URL is intended to be loaded into an ad iframe (or a fencedframe).

metadata

Null or a string. Extra arbitary information about this ad, passed to generateBid().

buyer reporting ID

Null or a string. Will be passed in place of interest group name to report win, subject to k-anonymity checks. Only meaningful in ads, but ignored in ad components.

buyer and seller reporting ID

Null or a string. Will be passed in place of interest group name or buyer reporting ID to report win and report result, subject to k-anonymity checks. Only meaningful in ads, but ignored in ad components.

allowed reporting origins

Null or a list of origins. A list of up to 10 reporting origins that can receive reports with registered macros. Each origin’s scheme must be "https" and each origin must be enrolled. Only meaningful in ads, but ignored in ad components.

A previous win is the interest group's auction win history, to allow on-device frequency capping. It’s a struct with the following items:

time

A moment. Approximate time the interest group won an auction.

ad json

A string. A JSON serialized object corresponding to the ad that won the auction.

A seller capability is a permission granted by an interest group to sellers. It’s "interest-group-counts" or "latency-stats". Each value represents a single bit in a 4-byte byte sequence. The 4-byte byte sequence can store no more than 32 capabilities.

Note: More than 2 values, but probably not more than 32 values are planned, at least for a while. This way, there is not need to reserve more space for a while.

14.2. Currency tag

A currency tag is a string containing exactly 3 upper-case ASCII letters, or null. The null value is used to denote that the currency is unspecified.
To serialize a currency tag given a currency tag currency:
  1. If currency is null, return "???".

  2. Return currency.

To check whether a string is a valid currency tag given string currencyString:
  1. If length of currencyString is not 3, return false.

  2. If currencyString[0] is not a ASCII upper alpha code point, return false.

  3. If currencyString[1] is not a ASCII upper alpha code point, return false.

  4. If currencyString[2] is not a ASCII upper alpha code point, return false.

  5. Return true.

To check a currency tag given the currency tags expected and actual:
  1. If expected is null, return true.

  2. If actual is null, return true.

  3. If actual is equal to expected, return true.

  4. Return false.

14.3. Auction config

An auction config is a struct with the following items:

seller

An origin. The origin of the seller running the ad auction. The scheme must be "https".

decision logic url

A URL. The URL to fetch the seller’s JavaScript from.

The decision logic url's origin will always be same origin with seller.

trusted scoring signals url

Null or a URL. Provide a mechanism for making real-time data (information about a specific ad creative) available for use at scoring time, e.g. the results of some ad scanning system.

When non-null, the trusted scoring signals url's origin will always be same origin with seller.

max trusted scoring signals url length

A long integer, initially 0. Indicates the maximum trusted scoring signals fetch url length for the auction config. 0 means no limit.

interest group buyers

Null or a list of origins. Owners of interest groups allowed to participate in the auction. Each origin’s scheme must be "https".

auction signals

Null, a string, a Promise, or failure. Opaque JSON data passed to both sellers' and buyers' script runners.

requested size

Null or an ad size, initially null. The size of the frame for the ad being selected by the auction.

all slots requested sizes

Null or a non-empty ordered set of ad sizes, initially null. The sizes of all frames for ads being selected by any auction in the frame.

seller signals

Null, a string, a Promise, or failure. Opaque JSON data passed to the seller’s script runner.

seller timeout

A duration in milliseconds, initially 50 milliseconds. Restricts the runtime of the seller’s scoreAd() script. If scoring does not complete before the timeout, the bid being scored is not considered further.

per buyer signals

Null, a Promise, failure, or an ordered map whose keys are origins and whose values are strings. Keys are buyers whose schemes must be "https". Values are opaque JSON data passed to corresponding buyer’s script runner.

per buyer timeouts

Null, a Promise, failure, or an ordered map whose keys are origins and whose values are durations in milliseconds. Keys are buyers whose schemes must be "https". Values restrict the runtime of corresponding buyer’s generateBid() script. If the timeout expires, only the bid submitted via setBid() is considered.

all buyers timeout

A duration in milliseconds, initially 50 milliseconds. Restricts the generateBid() script’s runtime for all buyers without a timeout specified in per buyer timeouts. If the timeout expires, only the bid submitted via setBid() is considered.

per buyer cumulative timeouts

Null, a Promise, failure, or an ordered map whose keys are origins and whose values are durations in milliseconds. Keys are buyers whose schemes must be "https". Values are collective timeouts for all interest groups of the buyer represented by the key. Includes the time of loading scripts and signals, and running the generateBid() functions. Once the timer expires, the affected buyer’s interest groups may no longer generate any bids. All bids generated before the timeout will continue to participate in the auction. Implementations should attempt, on a best-effort basis, to generate bids for each buyer in priority order, so lower priority interest groups are the ones more likely to be timed out. If Promises are passed in to the auction config for fields that support them, wait until configuration input promises resolve before starting the timer.

all buyers cumulative timeout

Null or a duration in milliseconds, initially null. Restricts a buyer’s cumulative timeout for all buyers without one specified in per buyer cumulative timeouts.

per buyer group limits

Null or an ordered map whose keys are origins and whose values are unsigned shorts. Keys are buyers whose schemes must be "https". Values restrict the number of bidding interest groups for a particular buyer that can participate in an auction.

all buyers group limit

An unsigned short, initially 65535. Limit on the number of bidding interest groups for all buyers without a limit specified in per buyer group limits.

per buyer priority signals

Null or an ordered map whose keys are origins and whose values are ordered maps, whose keys are strings and whose values are double. Per-buyer sparse vector whose dot product with priority vector is used to calculate interest group priorities. No signal’s key starts with "browserSignals.", which is reserved for values coming from the browser.

all buyers priority signals

Null or an ordered map whose keys are strings and whose values are double. Merged with per buyer priority signals before calculating per-interest group priorities. In the case both have entries with the same key, the entry in per_buyer_priority_signals takes precedence. No signals key start with "browserSignals.", which is reserved for values coming from the browser.

required seller capabilities

A set of seller capabilities. The seller capabilities that each interest group must declare to participate in the auction. Interest groups that don’t declare all these capabilities will not participate in the auction.

component auctions

A list of auction configs. Nested auctions whose results will also participate in a top level auction. Only the top level auction config can have component auctions.

deprecated render url replacements

Null, a Promise, failure, or a list of ad keyword replacements, each containing a single match and replacement. Render url replacements can only happen within a single seller auction config or within the component auction configs.

seller experiment group id

Null or an unsigned short, initially null. Optional identifier for an experiment group to support coordinated experiments with the seller’s trusted server.

per buyer experiment group ids

An ordered map whose keys are origins and whose values are unsigned shorts. Keys are buyers whose schemes must be "https". Values are identifiers for experiment groups, to support coordinated experiments with buyers' trusted servers.

all buyer experiment group id

Null or an unsigned short, initially null. Optional identifier for an experiment group to support coordinated experiments with buyers' trusted servers for buyers without a specified experiment group.

pending promise count

An integer, initially 0. The number of things that are pending that are needed to score everything. It includes waiting for Promises auction signals, per buyer signals, per buyer currencies, per buyer timeouts, direct from seller signals header ad slot, seller signals, or additionalBids whose Promises are not yet resolved.

config idl

AuctionAdConfig.

resolve to config

A boolean or a Promise, initially false. Whether the ad should be returned as a FencedFrameConfig, or otherwise as a urn uuid.

seller currency

A currency tag. Specifies the currency bids returned by scoreAd() are expected to use, and which reporting for this auction will agree on.

per buyer currencies

A Promise or failure or an ordered map whose keys are origins and whose values are currency tags. Specifies the currency bids returned by generateBid() or scoreAd() in component auctions are expected to use. The initial value is an empty map.

all buyers currency

A currency tag. Specifies the currency bids returned by generateBid() or scoreAd() in component auctions are expected to use if per buyer currencies does not specify a particular value.

direct from seller signals header ad slot

Null, a string, a Promise, or failure. Initially null.

auction nonce

Null or a version 4 UUID, initially null. A unique identifier associated with this and only this invocation of navigator.runAdAuction(). For multi-seller auctions, this ID is uniquely associated with all componentAuctions. This must come from a prior call to navigator.createAuctionNonce(). This is only required for auctions that provide additional bids, and each of those additional bids must use the same auction nonce to ensure that each of them was intended for this and only this auction.

expects additional bids

A boolean or failure, initially false. Specifies whether some bids will be provided as signed exchanges. Sets to failure if the additionalBids Promise is rejected.

To wait until configuration input promises resolve given an auction config auctionConfig:
  1. Wait until auctionConfig’s pending promise count is 0.

  2. Assert auctionConfig’s auction signals, seller signals, per buyer signals, per buyer currencies, per buyer timeouts, per buyer cumulative timeouts, deprecated render url replacements, and direct from seller signals header ad slot are not Promises, and expects additional bids is false.

  3. If auctionConfig’s auction signals, seller signals, per buyer signals, per buyer currencies, per buyer timeouts, per buyer cumulative timeouts, deprecated render url replacements, or direct from seller signals header ad slot is failure, return failure.

  4. Return.

To recursively wait until configuration input promises resolve given an auction config auctionConfig:
  1. For each componentAuctionConfig in auctionConfig’s component auctions:

    1. If the result of waiting until configuration input promises resolve given componentAuctionConfig is failure, return failure.

  2. Return the result of waiting until configuration input promises resolve given auctionConfig.

To handle an input promise in configuration given an auction config auctionConfig, a Promise p, and two sequences of steps, covering the parsing of the value and error-handling:
  1. Increment auctionConfig’s pending promise count.

  2. Let resolvedAndTypeChecked be the promise representing performing the following steps upon fulfillment of p with result:

    1. Execute the steps to be run for parsing of the value given result.

    2. If no exception was thrown in the previous step, then decrement auctionConfig’s pending promise count.

  3. Upon rejection of resolvedAndTypeChecked:

    1. Execute the steps for error-handling.

    2. Decrement auctionConfig’s pending promise count.

To look up per-buyer currency given an auction config auctionConfig, and an origin buyer:
  1. Let perBuyerCurrency be auctionConfig’s all buyers currency

  2. Assert that auctionConfig’s per buyer currencies is an ordered map.

  3. If auctionConfig’s per buyer currencies[buyer] exists, then set perBuyerCurrency to auctionConfig’s per buyer currencies[buyer].

  4. Return perBuyerCurrency

14.4. Bid generator

A per buyer bid generator is an ordered map whose keys are URLs representing trusted bidding signals urls, and whose values are per signals url bid generators.

A per signals url bid generator is an ordered map whose keys are origins representing joining origins, and whose values are lists of interest groups.

14.5. Generated bid

A generated bid is a bid that needs to be scored by the seller. The bid is either the result of evaluating a bidding script, or an additional bid provided by the `Ad-Auction-Additional-Bid` response headers. It’s a struct with the following items:

id

An unsigned long. Used to identify a generated bid.

for k-anon auction

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 value is zero or negative, then this interest group will not participate in the auction.

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().

ad

A string. JSON string to be passed to the scoring function.

TODO: Check whether ad descriptor can be moved to bid ad to avoid duplication (WICG/turtledove#868).

ad descriptor

An ad descriptor. Render URL and size of the bid’s ad.

ad component descriptors

Null or a list of ad descriptors. Ad components associated with bid, if any. May have at most 40 items. Must be null if the interest group making this bid has a null ad components field.

ad cost

Null or a double. Advertiser click or conversion cost passed from generateBid() to reportWin(). Negative values will be ignored and not passed. Will be stochastically rounded when passed.

modeling signals

Null or an unsigned short. A 0-4095 integer (12-bits) passed to reportWin(), with noising.

interest group

An interest group, whose generateBid() invocation generated this bid, or specified by the additional bid.

bid ad

The interest group ad within interest group to display.

modified bid

Null or a bid with currency. Being null for top level auction. The bid value a component auction’s scoreAd() script returns.

bid duration

A duration in milliseconds. How long it took to run generateBid().

provided as additional bid

A boolean, initially false.

component seller

Null or an origin. Seller in component auction which the interest group is participating. Only set for component auctions, null otherwise.

A bid debug reporting info is a struct with the following items:

id

An unsigned long-or-null. Matches a id of the generated bid corresponding to this reporting information, or null if no bid was produced, in which case the debug loss URLs are still relevant.

component seller

Null or an origin. Seller in component auction which was running to produce this reporting information. Only set for component auctions, null otherwise.

interest group owner

An origin. Matches owner of the interest group that was used to call generateBid() to produce this reporting information.

bidder debug win report url

Null or a URL, initially null. Set by generateBid()’s forDebuggingOnly's reportAdAuctionWin(url).

bidder debug loss report url

Null or a URL, initially null. Set by generateBid()’s forDebuggingOnly's reportAdAuctionLoss(url).

seller debug win report url

Null or a URL, initially null. In the case of a component auction, these are the values from component seller that the scored ad was created in. Set by scoreAd()’s forDebuggingOnly's reportAdAuctionWin(url).

seller debug loss report url

Null or a URL, initially null. In the case of a component auction, these are the values from component seller that the scored ad was created in. Set by scoreAd()’s forDebuggingOnly's reportAdAuctionLoss(url).

top level seller debug win report url

Null or a URL, initially null. Set in the case this bid was made in a component auction, won it, and was then scored by the top-level seller. Set by top-level seller’s scoreAd()’s forDebuggingOnly's reportAdAuctionWin(url).

top level seller debug loss report url

Null or a URL, initially null. Set in the case this bid was made in a component auction, won it, and was then scored by the top-level seller. Set by top-level seller’s scoreAd()’s forDebuggingOnly's reportAdAuctionLoss(url).

A bid with currency is a struct with the following items:

value

A double. The value of the bid.

currency

A currency tag. The currency the bid is in.

An ad descriptor is a struct with the following items:

url

A URL, which will be rendered to display the ad creative if this bid wins the auction.

size

Null or an ad size, initially null.

An ad size is a struct with the following items:

width

A double.

width units

A string. Can only be one of "px" (pixel), "sh" (screen height), and "sw" (screen width).

height

A double.

height units

A string. Can only be one of "px" (pixel), "sh" (screen height), and "sw" (screen width).

To parse an AdRender ad size given an object adSlotSize:
  1. If either adSlotSize["height"] or adSlotSize["width"] does not exist, return null.

  2. Let width and widthUnit be the dimension and dimension unit that results from running parse an AdRender dimension value with adSlotSize["width"], respectively.

  3. If width is null, return null.

  4. Let height and heightUnit be the dimension and dimension unit that results from running parse an AdRender dimension value with adSlotSize["height"], respectively.

  5. If height is null, return null.

  6. Let adSize be a new ad size.

  7. Set adSize’s width to width, width units to widthUnit, height to height, height units to heightUnit.

  8. Return adSize.

An ad keyword replacement is a struct with the following items:

match

A string, represents the match within a renderURL, that is going to be replaced by replacement. Must be in the format ${...} or %%...%%.

replacement

A string, meant to replace match within a renderURL.

14.6. Direct from seller signals

A direct from seller signals key is a struct with the following items:

seller

An origin. Matches the origin that served the captured `Ad-Auction-Signals` header.

ad slot

A string. Matches the adSlot key of the JSON dictionaries in the top-level array of the `Ad-Auction-Signals` value.

A direct from seller signals is a struct with the following items:

auction signals

Null or a string. Opaque JSON data passed to both buyers' and the seller’s script runners.

seller signals

Null or a string. Opaque JSON data passed to the seller’s script runner.

per buyer signals

A map whose keys are origins and whose values are strings. Keys are buyers whose scheme must be "https". Values are opaque JSON data passed to corresponding buyer’s script runner.

14.7. Score ad output

The output of running a Protected Audience scoreAd() script, is represented using the following type:

dictionary ScoreAdOutput {
  required double desirability;
  double bid;
  DOMString bidCurrency;
  double incomingBidInSellerCurrency;
  boolean allowComponentAuction = false;
};

Either a dictionary of this type, or a double, are handled as the return values.

The meanings of the fields are as follows:

desirability
Numeric score of the bid. Must be positive or the ad will be rejected. The winner of the auction is the bid which was given the highest score.
bid
Only relevant if this is a component auction. If present, this will be passed to the top-level seller’s scoreAd() and reportResult() methods instead of the original bid, if the ad wins the component auction and top-level auction, respectively.
bidCurrency
Only relevant if this is a component auction and bid is set. Specifies which currency the bid field is in.
incomingBidInSellerCurrency
Provides a conversion of the incoming bid to auction’s seller currency. This is different from bid which is the bid the component auction itself produces.
allowComponentAuction
If the bid being scored is from a component auction and this value is not true, the bid is ignored. This field must be present and true both when the component seller scores a bid, and when that bid is being scored by the top-level auction.

TODO: This also has an ad field, which should behave similar to the way bid affects modified bid, and then affecting the adMetadata parameter to scoreAd.

To process scoreAd output given an Completion Record result:
  1. If result is an an abrupt completion, return failure.

  2. If result.[[Value]] is a Number:

    1. Let checkedScore be the result of converting result.[[Value]] to a double.

    2. If an exception was thrown in the previous step, return failure.

    3. Let resultIDL be a new ScoreAdOutput.

    4. Set resultIDL’s desirability to checkedScore.

    5. Return resultIDL.

  3. Let resultIDL be the result of converting result.[[Value]] to a ScoreAdOutput.

  4. If an exception was thrown in the previous step, return failure.

  5. If resultIDL["bidCurrency"] exists and result of checking whether a string is a valid currency tag applied to resultIDL["bidCurrency"] is false, then return failure.

  6. Return resultIDL.

14.8. Leading bid info

A leading bid info is the information of the auction’s leading bid so far when ranking scored bids. It’s a struct with the following items:

top score

A double, initially 0.0. The highest score so far.

top non-k-anon-enforced score

A double, initially 0.0. The highest score so far when disregarding k-anonymity.

top bids count

An integer, initially 0. The number of bids with the same top score.

top non-k-anon-enforced bids count

Number of bids that are tied for leadership when disregarding k-anonymity thus far.

at most one top bid owner

A boolean, initially true. Whether all bids of top score are from the same interest group owner.

leading bid

Null or a generated bid, initially null. The leading bid of the auction so far.

leading non-k-anon-enforced bid

Null or a generated bid, initially null. The leading bid of the auction disregarding k-anonymity so far.

auction config

An auction config. The auction config of the auction which generated this leading bid.

second highest score

A double, initially 0.0. The second highest score so far. If more than one bids tie with top score, this will be set to top score.

highest scoring other bids count

An integer, initially 0. The number of bids with the same second highest score.

highest scoring other bid

Null or a generated bid. The second highest scoring other bid.

highest scoring other bid owner

Null or an origin, initially null. The interest group owner that made bids with the second highest score. Set to null if there are more than one owners made bids with the second highest score.

top level seller

Null or an origin. The seller in the top level auction. Only set for component auctions, null otherwise.

top level seller signals

Null or a string. Signals from the seller in the top level auction, produced as the output of the top-level seller’s reportResult() method. Only set for component auctions, null otherwise.

component seller

Null or an origin. Seller in component auction which generated this leading bid. Only set for the top level auction when component auctions are present, null otherwise.

bidding data version

Null or an unsigned long. Data-Version value from the trusted bidding signals server’s response(s). Will only be not null if the `Data-Version` header was provided and had a consistent value for all of the trusted bidding signals server responses used to construct the trustedBiddingSignals.

scoring data version

Null or an unsigned long. Data-Version value from the trusted scoring signals server’s response. Will only be not null if the `Data-Version` header was provided in the response headers from the trusted scoring signals server.

buyer reporting result

Null or a reporting result, initially null.

seller reporting result

Null or a reporting result, initially null.

component seller reporting result

Null or a reporting result, initially null.

A reporting result is a struct with the following items:

report url

Null or a URL, initially null. Set by sendReportTo(url).

reporting beacon map

Null or an ordered map whose keys are strings and whose values are URLs, initially null. Set by registerAdBeacon(map).

reporting macro map

Null or an ordered map whose keys are strings and whose values are strings, initially null. Set by registerAdMacro(name, value).

An auction report info is a struct with the following items:

debug win report urls

A list of URLs whose schemes must be "https". The winning bid’s generated bid's debug win report URLs.

debug loss report urls

A list of strings whose schemes must be "https". Losing bid’s generated bid's debug loss report URLs.

TODO: Change the two lists to a single URL since no more than one debug reports can be sent after downsampling debug reports. While the browser is experimenting with third party cookie deprecation (before they have been fully removed), the forDebuggingOnly reporting APIs are not downsampled, so they are still lists.

15. Privacy Considerations

Protected Audience aims to advance the privacy of remarketing and custom audience advertising on the web, so naturally privacy considerations are paramount to Protected Audience’s design. Partitioning data by site is the central mechanism to prevent joining a user’s identity across sites:

16. Security Considerations

Protected Audience involves the browser running untrusted JavaScript downloaded from multiple parties, so security concerns are top of mind. Fortunately Protected Audience is a highly constrained API not attempting to be a general purpose execution environment. Execution of this JavaScript is controlled and limited as follows:

Protected Audience has the browser pass in several “browserSignals” to the bidding script that give the script unforgeable information about the context that the script is being executed in. This way bidders and sellers have the choice to only participate in auctions where they are comfortable working with the involved parties.

The execution environment available to these scripts is the absolute minimum necessary to calculate a bid. It supports only ECMAScript. It does not support network, storage, timer, date, DOM, Workers, postMessage, Navigator or Window APIs.

Protected Audience adds Permission-Policies to control access to the Protected Audience APIs to give sites and embedders the ability to clamp down on use of the APIs as they see fit.

Auction config and interest group data are processed as JSON and not via the structured clone algorithm, in part because interest groups are updated via JSON server responses. However, there is also a security reason to not use the structured clone algorithm, which is that the data may be shared with other parties -- in particular, the auction config perBuyerSignals are sent from the seller to each buyer. Supporting structured cloning here would mean that buyer scripts would have to be prepared to handle arbitrary, complex, and potentially cyclic objects from the seller.

Index

Terms defined by this specification