Add description of ad object fields #558

brusshamilton · 2023-05-03T02:55:40Z

Adds descriptions for the adRenderId, sizeGroup, buyerReportingId, and buyerAndSellerReportingId fields and makes the exact field names more clear.

FLEDGE.md

JensenPaul · 2023-05-17T14:30:38Z

FLEDGE.md

+
+ * `sizeGroup`: The name of the sizeGroup that this ad is associated with.
+
+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, `adRenderId`, `sizeGroup`, and `metadata`. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via the `updateUrl` without losing `adComponents` stored in the interest group.


Suggested change

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, `adRenderId`, `sizeGroup`, and `metadata`. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via the `updateUrl` 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)). Similar to the `ads` field, each entry is an object that includes `renderURL`, and an optional `adRenderId` and `metadata`. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via the `updateUrl` without losing `adComponents` stored in the interest group.

each entry is an object that includes renderURL, and an optional adRenderId and metadata.

These three values (plus sizeGroup) are the only adComponent attributes that are actually used by PAAPI, yes?

If a component includes an optional adRenderId will only the id be sent in lieu of the entire serialised object for B&A auctions?

adsComponents --> adComponents

Fixed the typo. Yes, the optimization for B&A currently specifies that the adRenderId will be sent instead of the ad object.

JensenPaul · 2023-05-17T14:34:19Z

FLEDGE.md


-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 the `updateUrl` without losing `adComponents` stored in the interest group.
+ * `adRenderId`: A short identifier for this ad in this context. When this field is specified it will be sent instead of the full ad object for [B&A server auctions](https://github.com/WICG/turtledove/blob/main/FLEDGE_browser_bidding_and_auction_API.md).


We need to specify a type here, e.g. string or BigInt.

Done. It has been specified to be an 8 byte string.

Done. It has been specified to be an 8 byte string.

Is PAAPI UTF-8 all through?

Hmm that's an interesting point. JavaScript and ECMAScript strings are UTF-16 (e.g. charCodeAt() returns a 16-bit number). So does an 8-byte string imply at most 4 characters?

I think Chrome uses UTF-8 for strings internally, but that's a detail we shouldn't leak.

The intent was not to only be 4 characters, but rather to be 8 characters. Perhaps it would be better for us to define it as a ByteString instead of a DOMString. Then the IDL would perform the correct conversion and would enforce that each character's code was <= 255. That would ensure that the length of the JavaScript string and the length of the internal Chrome string was the same.

enforce that each character's code was <= 255

So a string value (whether in the adRenderId or some other string attribute such as a IG name, &c) containing say "Ā" (256) would cause Chrome to reject the entire input?

That is correct.

I could see IG owners perhaps using accented characters with codes > 255 in interest group names.
If there is not a warning about this constraint would you please add one in the docs?

We're not going to enforce that for interest group names, just for adRenderId.

dmdabbs · 2023-05-17T15:21:37Z

FLEDGE.md

@@ -155,9 +155,19 @@ The `executionMode` attribute is optional, and may contain one of the following
   mode does not have the same limitations on what top-level sites can join or leave
   the interest group.

-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 must contain an `renderUrl` property with the URL for the ad that would be shown. An ad may also have the following optional properties:


An ad may also have the following optional properties:

Wouldn't at least one sizeGroup be needed (it is part of the k-anon computation), else how would the auction determine an ad's suitability?

If an ad supports a single adSize, the sizeGroup value may be the name of that adSize, yes? I recall prior wording that is was unnecessary to declare single-size sizeGroups.

It will be needed eventually, but is not currently required. The timeline for including ad size in the k-anonymity calculation is yet to be determined.

Sorry I muddled two things there @brusshamilton. My

how would the auction determine an ad's suitability

intended to ask

how would the auction determine the ad's suitability to fit the ad slot dimensions absent a sizeGroup attribute?

Presumably the bidding script has some way of knowing. Either through the metadata associated with an ad or other data in the interest group.

We are going to be adding the sizeGroup eventually (see pull request #417), but it doesn't make sense to ad a reference to it before that pull request lands.

FLEDGE.md

Co-authored-by: Paul Jensen <JensenPaul@users.noreply.github.com>

SHA: 32e8f75 Reason: push, by JensenPaul Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

SHA: 32e8f75 Reason: push, by qingxinwu Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Add description of ad object fields

01b016f

sbelov reviewed May 3, 2023

View reviewed changes

FLEDGE.md Show resolved Hide resolved

miketaylr reviewed May 5, 2023

View reviewed changes

FLEDGE.md Outdated Show resolved Hide resolved

JensenPaul reviewed May 11, 2023

View reviewed changes

FLEDGE.md Outdated Show resolved Hide resolved

FLEDGE.md Outdated Show resolved Hide resolved

brusshamilton force-pushed the AdObj branch from b898865 to 01b016f Compare May 12, 2023 15:10

Address comments

0418c2d

JensenPaul reviewed May 17, 2023

View reviewed changes

dmdabbs reviewed May 17, 2023

View reviewed changes

FLEDGE.md Outdated Show resolved Hide resolved

brusshamilton added 4 commits May 17, 2023 15:39

Address comments

b67051e

make adRenderId a bytestring

346d162

in this context->in this interest group

a57b0a7

Fix typo

a26a726

JensenPaul reviewed May 23, 2023

View reviewed changes

FLEDGE.md Outdated Show resolved Hide resolved

JensenPaul reviewed May 23, 2023

View reviewed changes

FLEDGE.md Outdated Show resolved Hide resolved

Apply suggestions from code review

de8f061

Co-authored-by: Paul Jensen <JensenPaul@users.noreply.github.com>

JensenPaul merged commit 32e8f75 into WICG:main Jun 1, 2023

github-actions bot added a commit that referenced this pull request Jun 1, 2023

Merge pull request #558 from brusshamilton/AdObj

e22eb86

SHA: 32e8f75 Reason: push, by JensenPaul Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

brusshamilton deleted the AdObj branch June 16, 2023 14:39

JensenPaul mentioned this pull request Jun 26, 2023

FLEDGE: restricted reporting, training of bidding models #93

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add description of ad object fields #558

Add description of ad object fields #558

brusshamilton commented May 3, 2023

JensenPaul May 17, 2023

dmdabbs May 17, 2023

brusshamilton May 19, 2023

JensenPaul May 17, 2023

brusshamilton May 17, 2023

dmdabbs May 17, 2023

JensenPaul May 19, 2023

brusshamilton May 19, 2023

dmdabbs May 19, 2023 •

edited

Loading

brusshamilton May 19, 2023

dmdabbs May 19, 2023

brusshamilton May 22, 2023

dmdabbs May 17, 2023 •

edited

Loading

brusshamilton May 17, 2023

dmdabbs May 17, 2023 •

edited

Loading

brusshamilton May 17, 2023


		* `sizeGroup`: The name of the sizeGroup that this ad is associated with.

		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, `adRenderId`, `sizeGroup`, and `metadata`. Thanks to `ads` and `adsComponents` being separate fields, the buyer is able to update the `ads` field via the `updateUrl` 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 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 the `updateUrl` without losing `adComponents` stored in the interest group.
		* `adRenderId`: A short identifier for this ad in this context. When this field is specified it will be sent instead of the full ad object for [B&A server auctions](https://github.com/WICG/turtledove/blob/main/FLEDGE_browser_bidding_and_auction_API.md).

Add description of ad object fields #558

Add description of ad object fields #558

Conversation

brusshamilton commented May 3, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmdabbs May 19, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmdabbs May 17, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmdabbs May 17, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmdabbs May 19, 2023 •

edited

Loading

dmdabbs May 17, 2023 •

edited

Loading

dmdabbs May 17, 2023 •

edited

Loading