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
Changes from 1 commit
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
Prev Previous commit
Next Next commit
Describe size macros
  • Loading branch information
gtanzer committed Dec 13, 2022
commit bbc82b58416b6362b4bb5a3fb160b62576c52581
2 changes: 1 addition & 1 deletion FLEDGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ 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 a rendering URL, a named size group (see below), 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 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

Expand Down