Clarify or Update reportEvent Destinations

[trentunderwood]

Currently, reportEvent supports two “seller” destinations: seller and component-seller. The documentation does not define what these destinations refer to in a single-seller versus a multi-seller auction.

A naive guess might suppose that seller refers to only the top-level seller in a multi-seller auction and that component-seller does not refer to anyone in a single-seller auction.

Can we clarify whether this is indeed the case, and if not, add additional details to the documentation to clarify what these destinations mean?

If it is the case, then the current reportEvent API may be insufficient for buyers’ needs. This is because a buyer will likely need to report certain events to the “immediate” seller, meaning they would need to use seller as the destination if they won a single-seller auction, or component-seller if they won a multi-seller auction. This is problematic because the call to reportEvent will be triggered from within an ad, where there is no ability to determine what type of auction was run.
If the guess above is correct, then we propose two new seller destinations:

• top-level-seller: Refers to the only seller in a single-seller auction, or the top-level seller in a multi-seller auction.
• immediate-seller: Refers to the only seller in a single-seller auction, and the component seller in a multi-seller auction.

[shivanigithub]

@brusshamilton

[sbelov]

I wonder what would be a use case for top-level-seller as described in this issue (the only seller in a single-seller auction, or the top-level seller in a multi-seller auction). As I understand, in a given auction, a buyer typically has a direct relationship with and a visibility into the immediate seller upstream of them, but might not necessarily be aware of the presence of another top-level seller.

[shivanigithub]

@trentunderwood : your definition of seller and component-seller is correct.

IIUC the concern raised is that a reportEvent call is not aware of whether to send a beacon to the top-level seller or the component seller. Since registerAdBeacon can be invoked from both top-level and component sellers and reportEvent can contain [componentSeller, seller] to send a beacon to both, is that sufficient for your workflow?

[shivanigithub]

@trentunderwood : your definition of seller and component-seller is correct.

IIUC the concern raised is that a reportEvent call is not aware of whether to send a beacon to the top-level seller or the component seller. Since registerAdBeacon can be invoked from both top-level and component sellers and reportEvent can contain [componentSeller, seller] to send a beacon to both, is that sufficient for your workflow?

Or is the workflow such that top-level seller needs to be excluded from receiving the beacon which is not possible because reportEvent caller wouldn't know whether to put in seller or component seller?

[trentunderwood]

Or is the workflow such that top-level seller needs to be excluded from receiving the beacon which is not possible because reportEvent caller wouldn't know whether to put in seller or component seller?

Sort of. I imagine buyers might generally want to report events to the seller with which they have a direct relationship.

Since an ad can't know whether it won a single or multi seller auction, a buyer might use destination = ['seller', 'component-seller'] to ensure that the event is reported to the appropriate seller. The problem is that if the top-level seller happens to register an ad beacon with the same eventType, then the buyer would accidentally report an event to a seller they do not know, which seems problematic.

To @sbelov's question, I'm not actually sure what would be a use case for a buyer to report an event to the top-level seller in a multi-seller auction. reportEvent currently supports reporting events to the top-level seller, and I wasn't confident enough that there isn't a use case for this to suggest removing it. Perhaps a clearer way to frame the destinations is around whether or not the relationship between the buyer and seller is direct or indirect. For instance, the destinations could instead be direct-seller and indirect-seller. What do you think?

[sbelov]

@trentunderwood framing seller destinations around direct or indirect seems reasonable. I wonder someone could chime in from a potential FLEDGE buyer perspective.

@jonasz @fhoering in case you have feedback.

[shivanigithub]

In the interest of keeping the API surfaces changes minimum, a possible approach is to add an additional direct-seller destination type.
/cc @brusshamilton

For single-level auctions, seller and direct-seller both imply the same.
For multi-level auctions, component-seller and direct-seller both imply the same and seller implies the top-level seller.
(In the future component-seller can then be deprecated.)

[timphsieh-google]

@shivanigithub Thank you! I believe "direct-seller" should work. Do you have a timeline on when this could be added?

[brusshamilton]

The "direct-seller" destination was added in Chrome M112, and should already be available in the canary and development branches. It goes to beta on March 9, 2023 and stable on April 4, 2023.

[JensenPaul]

I think this issue is resolved. Feel free to reopen or file a new issue if you have more questions or issues.