Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API changes to make FLEDGE understand ad sizes #417

Merged
merged 63 commits into from
Oct 31, 2023
Merged
Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
63 commits
Select commit Hold shift + click to select a range
1a2368f
Update generateBid()
gtanzer Dec 12, 2022
ff42d5b
Most of joinAdInterestGroup changes
gtanzer Dec 13, 2022
d63d8e1
Expand description of joinAdInterestGroup fields
gtanzer Dec 13, 2022
8851afc
Add runAdAuction requestedSize field
gtanzer Dec 13, 2022
d662fb7
Update generateBid description
gtanzer Dec 13, 2022
038f2ca
Update FLEDGE.md
gtanzer Dec 13, 2022
7791d78
Update FLEDGE.md
gtanzer Dec 13, 2022
397e544
Update k-anon check
gtanzer Dec 13, 2022
19c08f5
Update FLEDGE.md
gtanzer Dec 13, 2022
bbc82b5
Describe size macros
gtanzer Dec 13, 2022
0251bbc
Update Release_Notes.md
gtanzer Dec 19, 2022
3ef5be6
Fix typo
gtanzer Jan 5, 2023
fc9653f
Describe how size returned from generateBid is used
gtanzer Jan 5, 2023
01ef829
Remove mention of filtering
gtanzer Jan 5, 2023
a0a310d
Describe purpose of sizes in interest group declaration
gtanzer Jan 5, 2023
1ddddee
Update Release_Notes.md
gtanzer Feb 8, 2023
d642777
Update Release_Notes.md
gtanzer Mar 30, 2023
f25854c
Update Release_Notes.md
gtanzer Mar 30, 2023
d119ceb
Merge branch 'main' into patch-3
JensenPaul Apr 7, 2023
5380368
Accept `sizeGroups` suggestion
gtanzer Apr 10, 2023
d102fbc
Accept suggestion
gtanzer Apr 11, 2023
47d50e6
Accept suggestion to use group1 and group2 in ad size example
gtanzer Apr 11, 2023
568873a
Accept suggestion to explicitly call out the "size3" example size->si…
gtanzer Apr 11, 2023
0a3db48
Accept suggestion to call out AD_WIDTH and AD_HEIGHT explicitly in "s…
gtanzer Apr 11, 2023
adf4cbc
Accept suggestion to turn "url+size" into "URL and size"
gtanzer Apr 11, 2023
cb668e8
Accept suggestion to rephrase interest group size declaration descrip…
gtanzer Apr 11, 2023
733a821
Mention optionality of interest group size fields
gtanzer Apr 24, 2023
3ec71ac
Remark that sizes are also optional in generateBid
gtanzer Apr 24, 2023
cfbcb70
Add more (optionally)s
gtanzer Apr 24, 2023
7c6aa0e
Update Release_Notes.md
gtanzer Apr 24, 2023
85c2f60
Add more optionality
gtanzer Apr 27, 2023
1e07855
Add more optionality
gtanzer Apr 27, 2023
c1e00cf
Update FLEDGE.md
gtanzer May 5, 2023
2d44dd9
Update FLEDGE.md
gtanzer May 5, 2023
7625240
Update FLEDGE.md
gtanzer May 5, 2023
9ecc5f6
Update FLEDGE.md
gtanzer May 5, 2023
4efd2e8
Update FLEDGE.md
gtanzer May 5, 2023
064841f
Update FLEDGE.md
gtanzer May 5, 2023
8199508
Update FLEDGE.md
gtanzer May 8, 2023
81a8bf9
Update FLEDGE.md
gtanzer May 8, 2023
7b856f7
Update FLEDGE.md
gtanzer May 8, 2023
0cc20cb
Update Release_Notes.md
gtanzer May 8, 2023
21795b9
Update requestedSize description
gtanzer May 8, 2023
ed3b830
Update browser signals
gtanzer May 8, 2023
cd73790
Update FLEDGE.md
gtanzer May 8, 2023
06ace19
Change M115 to M116 for browser signals additions
gtanzer May 26, 2023
ca80dd8
Fix "bid" -> "auction config"
gtanzer Jun 9, 2023
910a9f2
Remove renderSize from reportResult signals
gtanzer Jun 12, 2023
3170266
Merge branch 'main' into patch-3
gtanzer Aug 4, 2023
b65b04a
Update FLEDGE.md
gtanzer Aug 4, 2023
4d4364b
Update FLEDGE.md
gtanzer Aug 4, 2023
6e6ec85
Update FLEDGE.md
gtanzer Aug 8, 2023
975e965
Fix rebase issue
gtanzer Aug 8, 2023
c3fad7a
Add extra macro format
gtanzer Sep 1, 2023
cce7780
Fix {size: ...}
gtanzer Sep 1, 2023
3e34e0d
Merge branch 'main' into patch-3
gtanzer Oct 16, 2023
a3662d5
Add explicit transition period
gtanzer Oct 26, 2023
d69f233
Add explicit transition period
gtanzer Oct 26, 2023
2d3f228
Add explicit transition period
gtanzer Oct 26, 2023
a57adbe
Update FLEDGE.md
JensenPaul Oct 30, 2023
7148d74
Fix link and perens.
JensenPaul Oct 30, 2023
f8cd3f6
Update FLEDGE.md
JensenPaul Oct 31, 2023
50893b4
add missing space
JensenPaul Oct 31, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
46 changes: 35 additions & 11 deletions FLEDGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,8 +106,20 @@ const myGroup = {
'trustedBiddingSignalsUrl': ...,
'trustedBiddingSignalsKeys': ['key1', 'key2'],
'userBiddingSignals': {...},
'ads': [shoesAd1, shoesAd2, shoesAd3],
'adComponents': [runningShoes1, runningShoes2, gymShoes, gymTrainers1, gymTrainers2],
'ads': [{renderUrl: shoesAd1, sizeGroup: 'size1', ...},
{renderUrl: shoesAd2, sizeGroup: 'size2', ...},
{renderUrl: shoesAd3, sizeGroup: 'size3', ...}],
gtanzer marked this conversation as resolved.
Show resolved Hide resolved
'adComponents': [{renderUrl: runningShoes1, sizeGroup: 'group2', ...},
{renderUrl: runningShoes2, sizeGroup: 'group2', ...},
{renderUrl: gymShoes, sizeGroup; 'group2', ...},
{renderUrl: gymTrainers1, sizeGroup: 'size4', ...},
{renderUrl: gymTrainers2, sizeGroup: 'size4', ...}],
'adSizes': {'size1': {width: width1, height: height1},
'size2': {width: width2, height: height2},
'size3': {width: width3, height: height3},
'size4': {width: width4, height: height4}},
'sizeGroups:' {'group1': ['size1', 'size2', 'size3'],
'group2': ['size3', 'size4']},
};
const joinPromise = navigator.joinAdInterestGroup(myGroup, 30 * kSecsPerDay);
```
Expand Down Expand Up @@ -136,14 +148,18 @@ The `dailyUpdateUrl` provides a mechanism for the group's owner to periodically

The `executionMode` attribute is optional. The default value (`"compatibility"`) will run each invocation of `generateBid` in a totally fresh execution environment, which prevents one invocation from directly passing data to a subsequent invocation, but has non-trivial execution costs as each execution environment must be initialized from scratch. The `"groupByOrigin"` mode will attempt to re-use the execution environment for interest groups with the same script that were joined on the same top-level origin, which saves a lot of these initialization costs. However, to avoid cross-site information leaking into `generateBid`, attempts to join or leave an interest group in `"groupByOrigin"` mode from more than one top-level origin will result in all `"groupByOrigin"` interest groups that were joined from the same top-level origin being removed. When the execution environment is re-used the script top-level will not be re-executed, with only the `generateBid` function being run the subsequent times. This mode is intended for interest groups that are extremely likely to be joined or left from a single top-level origin only, with the probability high enough that the penalty of removal if the requirement doesn't hold to be low enough for the performance gains to be a worthwhile trade-off.

The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes both a rendering URL and arbitrary metadata that can be used at bidding time.
The `ads` list contains the various ads that the interest group might show. Each entry is an object that includes a rendering URL, a named size group (see below), and arbitrary metadata that can be used at bidding time. These render URLs may contain macros `{%AD_WIDTH%}` and `{%AD_HEIGHT%}`, which will be automatically replaced with the appropriate width and height after an auction, so that the initial resource request can fetch appropriately sized assets.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the concept of the size in the proposed change have a material impact on the behavior of the FLEDGE auction other than the substitution of macros in render URLs, and a K-anonymity check during the auction and reporting time?

That is, is there anything specific about the concept of a size that makes it worthwhile to have distinct size (comprised of width, height) semantics in the API? Does the concept of size introduced in the API impact (or need to impact) how a browser renders the winning ad?

A potential alternative would be a more generic concept of a "named creative variant" – that also can participate in a render URL macro substitution, as well as the K-anonymity checks.

Copy link
Contributor Author

@gtanzer gtanzer Jan 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the size returned from generateBid determines the size of the ad creative when it is loaded into a fenced frame from the ad creative's perspective, and the requestedSize passed into runAdAuction determines the size of the fenced frame from the embedder's perspective (unless overridden on the HTML element attributes). So the API does need to understand the width/height semantics. I thought I mentioned this but it looks like I forgot it when adapting the earlier proposal writeup. I'll fix it; thanks for noticing.

Are there any particular use cases for a "named creative variant" that you have in mind? We've previously talked about how fenced frames could support flexible sets of permissions (which would also need the API to have special understanding), and are thinking about how we might be able to handle things like native ads (which could pass an unstructured collection of information that the API doesn't need to understand, like you suggest).

Copy link

@sbelov sbelov Jan 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there any particular use cases for a "named creative variant" that you have in mind?

Didn't have immediate use cases in mind when I wrote this originally; perhaps, one could think about styling variants – background/highlight colors, fonts and text size, etc., while advertising essentially the same exact good or service, with styling depending on the publisher page context.

The reason I brought this up is to test whether the API complexity around an explicit concept of sizes is worth it, or whether some more general concept would suffice.

unless overridden on the HTML element attributes
It seems, then, that the embedder already has the ability to control the rendering size via FF attributes – and requestedSize would simply be an additional mechanism that does the same, not net new functionality, correct?

size returned from generateBid determines the size of the ad creative when it is loaded into a fenced frame from the ad creative's perspective
Does that impact rendering by the browser in some way? If so, how?

Copy link
Contributor Author

@gtanzer gtanzer Jan 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then in brief yes, it is necessary to have an explicit concept of sizes because it exists at the boundary between the embedder and the fenced frame content. For styling (this is what I meant by native ads), the fenced frame wouldn't need any understanding because the changes would be strictly inside the fenced frame content in JS, so the API could be more generic.

We are definitely still looking for ways to simplify the API while making it more flexible (in the long term). The main motivation for the k-anon check on sizes is to mitigate potential leaks from the network side channel in fenced frames, so if/when we can find a different solution there, we would likely be able to make this more generic/flexible (because there would be less concern about information flowing into the fenced frame).

It seems, then, that the embedder already has the ability to control the rendering size via FF attributes – and requestedSize would simply be an additional mechanism that does the same, not net new functionality, correct?

Correct, that's why it's forever-optional (not just opt-in for a transition period). But we figure that the publisher is probably telling the auction what size the ad slot is anyway, so they might as well use this field and avoid having to specify it again later in the HTML element attributes.

Does that impact rendering by the browser in some way? If so, how?

This is the browser's source of information for the size of the fenced frame's "inner frame" (i.e. the size of the content). In the old design, when you load a urn into a fenced frame, it freezes the size of the inner frame based on the size at the time of navigation (subject to an allow list), which causes all sorts of problems (privacy, but also performance because layout is asynchronous). In this new design, that frozen size comes synchronously from the urn/config instead.

gtanzer marked this conversation as resolved.
Show resolved Hide resolved
gtanzer marked this conversation as resolved.
Show resolved Hide resolved

The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes both a rendering URL and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group.
The `adComponents` field contains the various ad components (or "products") that can be used to construct ["Ads Composed of Multiple Pieces"](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#34-ads-composed-of-multiple-pieces)). Similarly to the `ads` field, each entry is an object that includes a rendering URL, a named size group (see below), and arbitrary metadata that can be used at bidding time. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via daily update without losing `adComponents` stored in the interest group.
gtanzer marked this conversation as resolved.
Show resolved Hide resolved

The `adSizes` field contains a dictionary of named ad sizes. Each size has the format `{width: widthVal, height: heightVal}`, where the values can have either pixel units (e.g. `100` or `'100px'`) or screen dimension coordinates (e.g. `100sw` or `100sh`). For example, the size `{width: '100sw', height: 50}` describes an ad that is the width of the screen and 50 pixels tall. The size `{width: '100sw', height: '200sw'}` describes an ad that is the width of the screen and has a 1:2 aspect ratio.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be helpful to describe more explicitly how these sizes would be used.

Copy link
Contributor Author

@gtanzer gtanzer Jan 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added some description of this immediately below, namely:

  • They're used to prefetch k-anonymity checks
  • When an ad with one of these sizes wins an auction, the size is substituted into URL macros
  • When the ad is loaded into a fenced frame, the browser freezes the fenced frame's inner dimensions to this size


The `sizeGroups` field contains a dictionary of named lists of ad sizes. Each ad declared above must specify a size group, saying which sizes it might be loaded at (for filtering during the auction and k-anonymity checks). Each named ad size is also considered a size group, so you don't need to manually define singleton size groups.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we clarify what filtering during the auction is being referred to here – and who (a browser, a buyer, or a seller) would be responsible for such filtering?

Below, it is mentioned that

optional requestedSize field recommends a frame size for the auction

and

Bidders inside the auction may pick a different size, but that resulting size will be scaled to fit inside the requested size.

This seems to imply that the browser would not be performing such filtering, and a seller and/or a buyer may choose – but do not have to – perform such filtering. Is that correct?

Copy link
Contributor Author

@gtanzer gtanzer Jan 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We haven't decided/specified what kind of filtering might happen yet. I meant that in the future, if there is demand for it, we could add the sizes to interest group filtering to help avoid unnecessary bidders. It's possible that you could fit that into the filtering framework already though; I'm not familiar with the details. I'll just delete this mention of filtering.


All fields that accept arbitrary metadata objects (`userBiddingSignals` and `metadata` field of ads) must be JSON-serializable.
All fields that specify URLs for loading scripts or JSON (`biddingLogicUrl`, `biddingWasmHelperUrl`, and `trustedBiddingSignalsUrl`) must point to URLs whose responses include the HTTP response header `X-Allow-FLEDGE: true` to ensure they are allowed to be used for loading FLEDGE resources.

The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough.
The browser will provide protection against microtargeting, by only rendering an ad if the same rendering URL is being shown to a sufficiently large number of people (e.g. at least 100 people would have seen the ad, if it were allowed to show). While in the [Outcome-Based TURTLEDOVE](https://github.com/WICG/turtledove/blob/master/OUTCOME_BASED.md) proposal this threshold applied only to the rendered creative, FLEDGE has the additional requirement that the tuple of the interest group owner, bidding script URL, and rendered creative (url+size) must be k-anonymous for an ad to be shown (this is necessary to ensure the current event-level reporting for interest group win reporting is sufficiently private). For interest groups that have component ads, all of the component ads must also separately meet this threshold for the ad to be shown. Since a single interest group can carry multiple possible ads that it might show, the group will have an opportunity to re-bid another one of its ads to act as a "fallback ad" any time its most-preferred choice is below threshold. This means that a small, specialized interest group that is still below the daily-update threshold could still choose to participate in auctions, bidding with a more-generic ad until the group becomes large enough.
gtanzer marked this conversation as resolved.
Show resolved Hide resolved


#### 1.3 Permission Delegation
Expand Down Expand Up @@ -187,6 +203,7 @@ const myAuctionConfig = {
'trustedScoringSignalsUrl': ...,
'interestGroupBuyers': ['https://www.example-dsp.com', 'https://buyer2.com', ...],
'auctionSignals': {...},
'requestedSize': {width: 100, height: 200},
'directFromSellerSignals: 'https://www.example-ssp.com/...',
'sellerSignals': {...},
'sellerTimeout': 100,
Expand Down Expand Up @@ -226,6 +243,8 @@ const auctionResultPromise = navigator.runAdAuction(myAuctionConfig);

This will cause the browser to execute the appropriate bidding and auction logic inside a collection of dedicated worklets associated with the buyer and seller domains. The `auctionSignals`, `sellerSignals`, and `perBuyerSignals` values will be passed as arguments to the appropriate functions that run inside those worklets — the `auctionSignals` are made available to everyone, while the other signals are given only to one party.

The optional `requestedSize` field recommends a frame size for the auction, which will be available to bidders in browser signals. Bidders inside the auction may pick a different size, but that resulting size will be scaled to fit inside the requested size. The returned fenced frame config will automatically populate a `<fencedframe>` with the right size when loaded, unless the size is overridden with the element attributes.
gtanzer marked this conversation as resolved.
Show resolved Hide resolved
gtanzer marked this conversation as resolved.
Show resolved Hide resolved

The optional `directFromSellerSignals` field can also be used to pass signals to the auction, similar to `sellerSignals`, `perBuyerSignals`, and `auctionSignals`. The difference is that `directFromSellerSignals` are trusted to come from the seller because the content loads from a [subresource bundle](https://github.com/WICG/webpackage/blob/main/explainers/subresource-loading.md) loaded from a seller's origin, ensuring the authenticity and integrity of the signals. For more details, see [2.5 directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals).

In some cases, multiple SSPs may want to participate in an auction, with the winners of separate auctions being passed up to another auction, run by another SSP. To facilitate these "component auctions", `componentAuctions` can optionally contain additional auction configurations for each seller's "component auction". The winning bid of each of these "component auctions" will be passed to the "top-level" auction. How bids are scored in this case is further described in [2.4 Scoring Bids in Component Auctions](#24-scoring-bids-in-component-auctions). The `AuctionConfig` of component auctions may not have their own `componentAuctions`.
Expand Down Expand Up @@ -452,8 +471,9 @@ generateBid(interestGroup, auctionSignals, perBuyerSignals,
...
return {'ad': adObject,
'bid': bidValue,
'render': renderUrl,
'adComponents': [adComponent1, adComponent2, ...],
'render': {url: renderUrl, size: {width: renderWidth, height: renderHeight}},
'adComponents': [{url: adComponent1, size: {width: componentWidth1, height: componentHeight1}},
{url: adComponent2, size: {width: componentWidth2, height: componentHeight2}}, ...],
'allowComponentAuction': false};
}
```
Expand All @@ -473,6 +493,7 @@ The arguments to `generateBid()` are:
{ 'topWindowHostname': 'www.example-publisher.com',
'seller': 'https://www.example-ssp.com',
'topLevelSeller': 'https://www.another-ssp.com',
'requestedSize': {width: 100, height: 200},
gtanzer marked this conversation as resolved.
Show resolved Hide resolved
'joinCount': 3,
'bidCount': 17,
'prevWins': [[time1,ad1],[time2,ad2],...],
Expand All @@ -490,8 +511,10 @@ The output of `generateBid()` contains the following fields:

* ad: (optional) Arbitrary metadata about the ad which this interest group wants to show. The seller uses this information in its auction and decision logic. If not present, it's treated as if the value were null.
* bid: A numerical bid that will enter the auction. The seller must be in a position to compare bids from different buyers, therefore bids must be in some seller-chosen unit (e.g. "USD per thousand"). If the bid is zero or negative, then this interest group will not participate in the seller's auction at all. With this mechanism, the buyer can implement any advertiser rules for where their ads may or may not appear.
gtanzer marked this conversation as resolved.
Show resolved Hide resolved
* render: A URL which will be rendered to display the creative if this bid wins the auction.
* adComponents: (optional) A list of up to 20 adComponent strings from the InterestGroup's adComponents field. Each value must match an adComponent renderUrl exactly. This field must not be present if the InterestGroup has no adComponent field. It is valid for this field not to be present even when adComponents is present. (See ["Ads Composed of Multiple Pieces"](#34-ads-composed-of-multiple-pieces) below.)
* render: A dictionary describing the creative that should be rendered if this bid wins the auction. This includes:
gtanzer marked this conversation as resolved.
Show resolved Hide resolved
* url: The creative's URL.
* size: A dictionary containing `width` and `height` fields, describing the creative's size (see the interest group declaration above).
* adComponents: (optional) A list of up to 20 adComponent strings from the InterestGroup's adComponents field. Each value must match an adComponent renderUrl and size exactly. This field must not be present if the InterestGroup has no adComponent field. It is valid for this field not to be present even when adComponents is present. (See ["Ads Composed of Multiple Pieces"](#34-ads-composed-of-multiple-pieces) below.)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Back to the subject discussed on the Fledge call - https://github.com/WICG/turtledove/blob/main/meetings/2022-11-09-FLEDGE-call-minutes.md and in the github issue - #312 (comment):
to be able to implement carousel (or other type of animation in creative that present single product in two ways) we should define each product twice - which effectively - decrease this constraint to 10.
Could you consider two options:

  • increase limit from 20 to 40 ?
  • or limit 20 would only verify unique adComponent renderUrls (duplicated urls would be treated as single)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll discuss this and get back to you. From my perspective, the latter option sounds pretty unobjectionable, but I wasn't involved in picking the original max number of components so there might be something I'm missing.

gtanzer marked this conversation as resolved.
Show resolved Hide resolved
* allowComponentAuction: If this buyer is taking part of a component auction, this value must be present and true, or the bid is ignored. This value is ignored (and may be absent) if the buyer is part of a top-level auction.

`generateBid()` has access to the `setPrioritySignalsOverride(key, value)` method. This adds an entry to the current interest group's `prioritySignalsOverrides` dictionary with the specified `key` and `value`, overwriting the previous value, if there was already an entry with `key`. If `value` is null, the entry with the specified key is deleted, if it exists.
Expand Down Expand Up @@ -622,6 +645,7 @@ The arguments to this function are:
'componentSeller': 'https://www.some-other-ssp.com',
'interestGroupOwner': 'https://www.example-dsp.com/',
'renderUrl': 'https://cdn.com/url-of-winning-creative.wbn',
'renderSize': {width: 100, height: 200},
gtanzer marked this conversation as resolved.
Show resolved Hide resolved
'bid:' bidValue,
'desirability': desirabilityScoreForWinningAd,
'topLevelSellerSignals': outputOfTopLevelSellersReportResult,
Expand All @@ -633,7 +657,7 @@ The arguments to this function are:
* sellerSignals: Like auctionConfig.sellerSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?sellerSignals`.
* auctionSignals: Like auctionConfig.auctionSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?auctionSignals`.

The `browserSignals` argument must be handled carefully to avoid tracking. It certainly cannot include anything like the full list of interest groups, which would be too identifiable as a tracking signal. The `renderUrl` can be included since it has already passed a k-anonymity check. The browser may limit the precision of the bid and desirability values to avoid these numbers exfiltrating information from the interest group's `userBiddingSignals`. On the upside, this set of signals can be expanded to include useful additional summary data about the wider range of bids that participated in the auction, e.g. the second-highest bid or the number of bids. Additionally, the `dataVersion` will only be present if the `Data-Version` header was provided in the response headers from the Trusted Scoring server.
The `browserSignals` argument must be handled carefully to avoid tracking. It certainly cannot include anything like the full list of interest groups, which would be too identifiable as a tracking signal. The `renderUrl` and `renderSize` can be included since they hvae already passed a k-anonymity check. The browser may limit the precision of the bid and desirability values to avoid these numbers exfiltrating information from the interest group's `userBiddingSignals`. On the upside, this set of signals can be expanded to include useful additional summary data about the wider range of bids that participated in the auction, e.g. the second-highest bid or the number of bids. Additionally, the `dataVersion` will only be present if the `Data-Version` header was provided in the response headers from the Trusted Scoring server.

The `reportResult()` function's reporting happens by directly calling network APIs in the short-term, but will eventually go through the Private Aggregation API once it has been developed. The output of this function is not used for reporting, but rather as an input to the buyer's reporting function.

Expand All @@ -655,7 +679,7 @@ The arguments to this function are:

* auctionSignals and perBuyerSignals: As in the call to `generateBid()` for the winning interest group.
* sellerSignals: The output of `reportResult()` above, giving the seller an opportunity to pass information to the buyer. In the case where the winning buyer won a component auction and then went on to win the top-level auction, this is the output of component auction's seller's `reportResult()` method.
* browserSignals: Similar to the argument to `reportResult()` above, though without the seller's desirability score, but with an additional `seller` field. `browserSignals` may also contain the `interestGroupName` if the tuple of interest group owner, name, bidding script URL and ad creative URL were jointly k-anonymous. The `dataVersion` field will contain the `Data-Version` from the trusted bidding signals response headers if they were provided by the trusted bidding signals server response and the version was consistent for all keys requested by this interest group, otherwise the field will be absent. If the winning bid was from a component auction, then `seller` will be the seller in the component auction, a `topLevelSeller` field will contain the seller of the top level auction. Additional fields could also include some buyer-specific signal like the second-highest bid from that particular buyer.
* browserSignals: Similar to the argument to `reportResult()` above, though without the seller's desirability score, but with an additional `seller` field. `browserSignals` may also contain the `interestGroupName` if the tuple of interest group owner, name, bidding script URL and ad creative URL+size were jointly k-anonymous. The `dataVersion` field will contain the `Data-Version` from the trusted bidding signals response headers if they were provided by the trusted bidding signals server response and the version was consistent for all keys requested by this interest group, otherwise the field will be absent. If the winning bid was from a component auction, then `seller` will be the seller in the component auction, a `topLevelSeller` field will contain the seller of the top level auction. Additional fields could also include some buyer-specific signal like the second-highest bid from that particular buyer.
gtanzer marked this conversation as resolved.
Show resolved Hide resolved
* directFromSellerSignals is an object that may contain the following fields:
* perBuyerSignals: Like auctionConfig.perBuyerSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?perBuyerSignals=[origin]`.
* auctionSignals: Like auctionConfig.auctionSignals, but passed via the [directFromSellerSignals](#25-additional-trusted-signals-directfromsellersignals) mechanism. These are the signals whose subresource URL ends in `?auctionSignals`.
Expand Down