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

Supporting creative macros in FLEDGE #477

Open
sewoomg opened this issue Mar 7, 2023 · 14 comments
Open

Supporting creative macros in FLEDGE #477

sewoomg opened this issue Mar 7, 2023 · 14 comments
Labels
Non-breaking Feature Request Feature request for functionality unlikely to break backwards compatibility

Comments

@sewoomg
Copy link
Contributor

sewoomg commented Mar 7, 2023

Context

Third-party tracking is a feature that advertisers commonly use when buying through DSPs. There are many use cases for 3p tracking, and one example is to allow unified reporting across multiple DSPs over time.

3p tracking works through the use of creative macros. The advertiser configures html + js, or specific tracking URLs, as a part of their creatives in the DSP UI. These creatives can contain macros, which are meant to be populated/replaced with contextual and ad-related data at rendering time.

With FLEDGE, when rendering into a Fenced Frame, the DSP does not have contextual data at rendering time and cannot populate macros that include contextual data. While Fenced Frame Ads Reporting (FFAR) can be used to send both contextual and ad-related signals, use of FFAR will require the DSP to know all of the 3p URL endpoints and coordinate with each of the vendors to identify all events tracked and agree on url formats. Instead, we propose preserving macro functionality and creating a new way to populate these macros.

Proposal

  1. Add a new function, RegisterAdMacro, similar to RegisterAdBeacon, to allow the reporting worklet to 1)pass contextual/publisher data and 2)control which 3p tracking vendor get access to data, via Fenced Frame reportEvent calls.

RegisterAdMacro takes 3 arguments:

  • macro_name: a string that can appear in destination_template when calling reportEventWithMacros
  • macro_value: a string that Chrome will use to replace instances of macro_name in destination_template.
  • origin_allowlist: a list of destination origins allowed to receive this macro value. Can be set to "*" to allow replacement in all destination origins.
  1. Modify reportEvent, or define a new function reportEventWithMacros, to allow passing a URL containing macros that will be populated with the signals set from the reporting worklet before sending the beacon.

Example

An advertiser adds the following to their creative tag to count viewable impressions and attribute those to a specific campaign, publisher and website.

<script src='https://adtech.example/measurement?cid=${CAMPAIGN_ID}&pub_id=${PUBLISHER_ID}&site=${SOURCE_URL_ENC}&x=123>

In buyer's reportWin worklet, the DSP registers AdBeacons and AdMacros:

RegisterAdMacro('PUBLISHER_ID', 444, '*');
//This macro will be populated for all origins as denoted by '*'
RegisterAdMacro('SOURCE_URL_ENC', 'http%3A%2F%2Fpub%2Eexample%2Fpage', 'adtech.example');
//This macro will only be populated when origin matches what is allowed in the third argument, 'adtech.example'

When rendering the creative, the DSP would replace macros that do not require contextual/publisher information as part of rendering, including ${CAMPAIGN_ID} in this example, so the tag sent to the browser would be:

<script src='https://adtech.example/measurement?cid=555&pub_id=${PUBLISHER_ID}&site=${SOURCE_URL_ENC}&x=123>

The script returned can use the new version of reportEvent to send reporting pings with contextual data populated by chrome at a time of the 3p vendor's choosing. For example:

window.fence.reportEventWithMacros({
  'destination_template': 'https://adtech.example/impression?cid=555&pub_id=${PUBLISHER_ID}&site=${SOURCE_URL_ENC}&t=123'
});

Chrome would replace the ${PUBLISHER_ID} and ${SOURCE_URL_ENC} macros with the values registered in reportWin before sending the request. So the 3p vendor receives the beacon at

https://adtech.example/impression?cid=555&pub_id=444&site=http%3A%2F%2Fpub%2Eexample%2Fpage&t=123

@TheTamFamily
Copy link
Contributor

I would also like to discuss the possibility of having these macros available in the reportWin API so the advertiser can use them to determine the effectiveness of their ad spend.

@sewoomg
Copy link
Contributor Author

sewoomg commented Apr 4, 2023

Upon reviewing the proposal during the WIGC call last week, we realized it’s important to put in more control as to who can gain access to the data registered through the RegisterAdMacro function. Our suggestion is to update the third argument, origin_allowlist, to disallow “*” as an option and turn it into an array with at most 10 origins. Since origins should be mostly stable per creative, and they can be set as part of ad metadata during joinInterestGroup, right next to the render URL, which can be later be accessed by DSP during reportWin.

Separately, we want to clarify that these macros are intended for reporting only and should not affect rendering. That is why macro replacement can only happen in reportWin, which will prevent macros from being used in rendering.

@sewoomg
Copy link
Contributor Author

sewoomg commented Apr 26, 2023

One additional request regarding the proposal above. We would like reportEventWithMacros to be sent as GET 1) so that existing trackers can be called without needing to validate that they accept POST requests and 2) as we do not need any event data to be sent with reportEventWithMacros.

@ajvelasquezgoog
Copy link
Collaborator

ajvelasquezgoog commented May 19, 2023

Thanks @sewoomg for suggesting. We have reviewed it extensively and we agree with most of the proposal.

As a reminder and as per our February 9th blogpost indeed we have decided to extend event-level win reporting until at least 2026. So, addressing use cases in Protected Audience (f.k.a FLEDGE) that the ecosystem finds necessary to continue supporting now is important to us. We believe this one to be such a use case; allowing DSPs to continue supporting macros to send reports to 3rd party measurement/tracking providers. This ensures advertisers can continue to fairly measure the impact of their spend across competing DSPs for a given campaign, thus providing a level playing field for adtech.

This proposal builds on the infrastructure we have made available to support event-level reporting within Fenced Frames, detailed in this explainer. We encourage folk to read that first to fully understand the proposal being discussed here.

We’d like to propose important amendments and additions as our reply:

  1. We will extend the support to both Fenced Frames and URN-iframes, so that adtech can implement and take advantage of this now without requiring use of Fenced Frames
  2. We cannot support a origin_allowlist that takes “*” as an argument, but we will enable the allowlist to be populated with the intended destinations, up to a maximum of 10 destinations per ad rendered.
  3. Each of the destinations’ origins will be checked against our recently announced Privacy Sandbox developer enrollment system. If any one of the destinations is not enrolled, it will be skipped and the AdBeacon for that specific destination will not be sent.
  4. The origin_allowlist is defined as part of the adsMetadata in the IG, not passed to registerAdMacro

We believe that with these modifications we have a way to implement this use case in a way that limits who learns about the user’s browsing behavior while event-level reporting is available.

@sewoomg
Copy link
Contributor Author

sewoomg commented Jun 2, 2023

Thanks for the thorough response @ajvelasquezgoog.

For 4, we propose following a format similar to below to put origin_allowlist inside the metadata.

{
  'renderUrl': 'https://cdn.example/.../bikeAd1.html',
  'metadata': { 'origin_allowlist': {'blah.com', ...} }
}

@dmdabbs
Copy link
Contributor

dmdabbs commented Jun 4, 2023

  'metadata': { 'origin_allowlist': {'blah.com', ...} }

The metadata attribute has been a tabula rasa for arbitrary, IG-provided stuff. A system-recognised attribute within it should at least be clearly scoped to its purpose, say,

  'metadata': { 'reporting_origins_allowed': ['blah.com', ...] }

or ffar_origins_allowed.

Also it should be an array versus a dict, if it is a list of no more than ten items.

If the list exceeds ten, does that deep six the entire IG? Just this creative? Are the value(s) greater than index 9 simply dropped?

@ajvelasquezgoog
Copy link
Collaborator

ajvelasquezgoog commented Jun 5, 2023

Great suggestions! So yes, here are a couple clarifications:

  1. The allowlist will have the following format:
    { 'renderUrl': 'https://cdn.example/.../bikeAd1.html', 'reporting_origins_allowed': ['blah.com', ...] }

  2. Thanks for the question @dmdabbs , we are going here with the path of least resistance, which is we will simply truncate the list on our side at the maximum defined length and drop the values great than index 9

@TheTamFamily
Copy link
Contributor

@ajvelasquezgoog : Thought I chime in here as I'm not sure how your suggestion solves the passing of Ad Macros to the buying platform. I understand that the reporting data can b fed back to an "allow list of origins" and I assume that this can be different from IG owner's origin / domain.

Will the sell side / publisher be able to populate the Ad Macros as signals that can be passed in the reportWin API? If so what are the standard Ad Macros that will be supported. Currently, for example in Campaign Manager 360, they support macros for site ID, creative ID, campaign ID.

@JensenPaul JensenPaul added the Non-breaking Feature Request Feature request for functionality unlikely to break backwards compatibility label Jun 22, 2023
@keweigegoog
Copy link

Two additional clarifications for the request:

  1. The current reportEvent initiated beacon includes ARA headers. Please also include ARA headers for the reportEventWithMacros initiated beacons (i.e., GET requests).
  2. We understand the 'reserved.top_navation' event type is reserved for top level navigation on clicks. We are fine with the reportEventWithmacros API not supporting automatic beacons.

chromium-wpt-export-bot pushed a commit to web-platform-tests/wpt that referenced this issue Jul 25, 2023
This CL adds the API surface for custom destination urls in reportEvent.

Later CLs will send this information to the browser and send reporting
beacons based on it.

WICG/turtledove#477

Change-Id: If901ceb39f759a2911e1781d91caf133874ac389
chromium-wpt-export-bot pushed a commit to web-platform-tests/wpt that referenced this issue Jul 25, 2023
This CL adds the API surface for custom destination urls in reportEvent.

Later CLs will send this information to the browser and send reporting
beacons based on it.

WICG/turtledove#477

Change-Id: If901ceb39f759a2911e1781d91caf133874ac389
aarongable pushed a commit to chromium/chromium that referenced this issue Jul 25, 2023
This CL adds the API surface for custom destination urls in reportEvent.

Later CLs will send this information to the browser and send reporting
beacons based on it.

WICG/turtledove#477

Change-Id: If901ceb39f759a2911e1781d91caf133874ac389
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4711374
Reviewed-by: Dominic Farolino <[email protected]>
Reviewed-by: Shivani Sharma <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1175044}
chromium-wpt-export-bot pushed a commit to web-platform-tests/wpt that referenced this issue Jul 25, 2023
This CL adds the API surface for custom destination urls in reportEvent.

Later CLs will send this information to the browser and send reporting
beacons based on it.

WICG/turtledove#477

Change-Id: If901ceb39f759a2911e1781d91caf133874ac389
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4711374
Reviewed-by: Dominic Farolino <[email protected]>
Reviewed-by: Shivani Sharma <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1175044}
chromium-wpt-export-bot pushed a commit to web-platform-tests/wpt that referenced this issue Jul 25, 2023
This CL adds the API surface for custom destination urls in reportEvent.

Later CLs will send this information to the browser and send reporting
beacons based on it.

WICG/turtledove#477

Change-Id: If901ceb39f759a2911e1781d91caf133874ac389
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4711374
Reviewed-by: Dominic Farolino <[email protected]>
Reviewed-by: Shivani Sharma <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1175044}
aarongable pushed a commit to chromium/chromium that referenced this issue Aug 2, 2023
This CL adds a no-op mojo interface, which is exercised by WPTs added
in the previous CL.

The next CL will actually implement and test the browser side of the
API (reusing much of the existing FencedFrameReporter implementation).

CL 1/N: https://chromium-review.googlesource.com/c/chromium/src/+/4711374

WICG/turtledove#477

Change-Id: I21a2072fae8663a797432501077ff182b568e03c
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4721545
Reviewed-by: Dominic Farolino <[email protected]>
Reviewed-by: Alex Moshchuk <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1178188}
@gtanzer
Copy link
Contributor

gtanzer commented Aug 2, 2023

To make the API surface cleaner, we are planning on replacing:

window.fence.reportEventWithMacros({
  'destination_template': 'https://adtech.example/impression?cid=555&pub_id=${PUBLISHER_ID}&site=${SOURCE_URL_ENC}&t=123'
});

with:

window.fence.reportEvent({
  'destinationURL': 'https://adtech.example/impression?cid=555&pub_id=${PUBLISHER_ID}&site=${SOURCE_URL_ENC}&t=123'});

(This is strictly renaming, no functional difference.)

moz-v2v-gh pushed a commit to mozilla/gecko-dev that referenced this issue Aug 2, 2023
…estination urls [1/N], a=testonly

Automatic update from web-platform-tests
Fenced frames: Add reporting to custom destination urls [1/N]

This CL adds the API surface for custom destination urls in reportEvent.

Later CLs will send this information to the browser and send reporting
beacons based on it.

WICG/turtledove#477

Change-Id: If901ceb39f759a2911e1781d91caf133874ac389
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4711374
Reviewed-by: Dominic Farolino <[email protected]>
Reviewed-by: Shivani Sharma <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1175044}

--

wpt-commits: 18f69d13d720ecd631631b4e9aee95bd27fc84e4
wpt-pr: 41167
ErichDonGubler pushed a commit to erichdongubler-mozilla/firefox that referenced this issue Aug 4, 2023
…estination urls [1/N], a=testonly

Automatic update from web-platform-tests
Fenced frames: Add reporting to custom destination urls [1/N]

This CL adds the API surface for custom destination urls in reportEvent.

Later CLs will send this information to the browser and send reporting
beacons based on it.

WICG/turtledove#477

Change-Id: If901ceb39f759a2911e1781d91caf133874ac389
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4711374
Reviewed-by: Dominic Farolino <[email protected]>
Reviewed-by: Shivani Sharma <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1175044}

--

wpt-commits: 18f69d13d720ecd631631b4e9aee95bd27fc84e4
wpt-pr: 41167
aarongable pushed a commit to chromium/chromium that referenced this issue Aug 7, 2023
This CL implements browser-side handling of reportEvent to custom
destination URLs, without macro substitution.

The next (and final) CL will substitute macros into the custom URL and
check that the destination origin is on an allowlist. Those changes are
blocked on this CL:
https://chromium-review.googlesource.com/c/chromium/src/+/4727181

WICG/turtledove#477

Change-Id: I6267176d62d4832cc8f8917ff8ab0ad80f3122ae
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4725286
Reviewed-by: Shivani Sharma <[email protected]>
Reviewed-by: Theodore Olsauskas-Warren <[email protected]>
Reviewed-by: Alex Moshchuk <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Reviewed-by: Dominic Farolino <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1180251}
aarongable pushed a commit to chromium/chromium that referenced this issue Aug 8, 2023
Gate this new surface of the reportEvent API behind a feature flag.

WICG/turtledove#477

Change-Id: I24686173a489ef1c6775c537a26c95c3b185d52a
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4752873
Commit-Queue: Garrett Tanzer <[email protected]>
Reviewed-by: Shivani Sharma <[email protected]>
Reviewed-by: Arthur Sonzogni <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1180965}
aarongable pushed a commit to chromium/chromium that referenced this issue Aug 16, 2023
Finish reportEvent to custom destination URLs:
* If the destination origin isn't an allowed origin, disallow all future
  reports to custom destination URLs from this FencedFrameReporter.
* Substitute macros into the destination URL.

WICG/turtledove#477

Change-Id: I222c94bf41d559b549a108834abb485ba0787e43
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4753243
Reviewed-by: Shivani Sharma <[email protected]>
Reviewed-by: Qingxin Wu <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1184195}
@thegreatfatzby
Copy link
Contributor

Really really great to see this moving forward, quick clarification:

  • The K-Anon checks won't be impacted, because it will be based on the un-replaced macro?
  • The macro names can be anything?
  • The macro values can be anything available in the reportWin function?

@ajvelasquezgoog
Copy link
Collaborator

Hi @thegreatfatzby :

  1. k-anon checks won't be impacted because reporting destinations are not checked for k-anon.

  2. Technically yes, but in reality the selection is limited from the menu of macros the buyer/DSP makes available. For example, look at DV3's list here: https://support.google.com/displayvideo/answer/2789508?hl=en and Xandr's list here: https://docs.xandr.com/bundle/invest_invest-standard/page/topics/supported-creative-macros.html .

  3. Yes

blueboxd pushed a commit to blueboxd/chromium-legacy that referenced this issue Sep 10, 2023
…URLs [4/N]

Finish reportEvent to custom destination URLs:
* If the destination origin isn't an allowed origin, disallow all future
  reports to custom destination URLs from this FencedFrameReporter.
* Substitute macros into the destination URL.

WICG/turtledove#477

(cherry picked from commit 95148e4)

Change-Id: I222c94bf41d559b549a108834abb485ba0787e43
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4753243
Reviewed-by: Shivani Sharma <[email protected]>
Reviewed-by: Qingxin Wu <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Cr-Original-Commit-Position: refs/heads/main@{#1184195}
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4790842
Bot-Commit: Rubber Stamper <[email protected]>
Commit-Queue: Prudhvikumar Bommana <[email protected]>
Cr-Commit-Position: refs/branch-heads/5938@{#280}
Cr-Branched-From: 2b50cb4-refs/heads/main@{#1181205}
aarongable pushed a commit to chromium/chromium that referenced this issue Sep 12, 2023
Add extra checks on the destination URL for macro substitution. These
checks should be covered by existing checks, but the new versions should
be more robust to future changes and give more helpful error messages.

WICG/turtledove#477

Change-Id: I406c7da718cb7a757b3fffc8af0795490e64f166
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4818548
Reviewed-by: Shivani Sharma <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1195573}
aarongable pushed a commit to chromium/chromium that referenced this issue Sep 15, 2023
Add input sanitization for the macro keys/values to prevent them from
breaking out of their url query parameters.

WICG/turtledove#477

Change-Id: I5e822378064d32330ba652e11b4edde5e8acb260
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4842629
Reviewed-by: Qingxin Wu <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Reviewed-by: Daniel Cheng <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1197342}
@thegreatfatzby
Copy link
Contributor

Additional clarification: will we be able to see the list of Ad Tech's enrolled, so as to discuss w/them if they are not?

@thegreatfatzby
Copy link
Contributor

I think I can sort of self answer from here:

3. As an app developer, can I verify if an SDK or site has enrolled?
After the enforcement deadline in mid-October 2023, we will publish a list of currently enrolled sites and SDKs for verification purposes, along with their enrollment IDs.

Lightning00Blade pushed a commit to Lightning00Blade/wpt that referenced this issue Dec 11, 2023
This CL adds the API surface for custom destination urls in reportEvent.

Later CLs will send this information to the browser and send reporting
beacons based on it.

WICG/turtledove#477

Change-Id: If901ceb39f759a2911e1781d91caf133874ac389
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4711374
Reviewed-by: Dominic Farolino <[email protected]>
Reviewed-by: Shivani Sharma <[email protected]>
Commit-Queue: Garrett Tanzer <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1175044}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Non-breaking Feature Request Feature request for functionality unlikely to break backwards compatibility
Projects
None yet
Development

No branches or pull requests

8 participants