Supporting creative macros in FLEDGE #477

sewoomg · 2023-03-07T20:29:42Z

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

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.

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.

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:

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

The text was updated successfully, but these errors were encountered:

TheTamFamily · 2023-03-27T08:23:14Z

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 · 2023-04-04T16:21:27Z

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 · 2023-04-26T23:11:17Z

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 · 2023-05-19T17:30:01Z

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:

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
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.
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.
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 · 2023-06-02T17:11:14Z

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 · 2023-06-04T19:39:49Z

  '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 · 2023-06-05T17:04:54Z

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

The allowlist will have the following format:
{ 'renderUrl': 'https://cdn.example/.../bikeAd1.html', 'reporting_origins_allowed': ['blah.com', ...] }
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 · 2023-06-22T15:47:23Z

@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.

keweigegoog · 2023-07-18T21:03:20Z

Two additional clarifications for the request:

The current reportEvent initiated beacon includes ARA headers. Please also include ARA headers for the reportEventWithMacros initiated beacons (i.e., GET requests).
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.

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

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}

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 · 2023-08-02T20:27:04Z

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.)

…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

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}

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}

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 · 2023-08-24T23:07:15Z

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 · 2023-08-29T00:01:03Z

Hi @thegreatfatzby :

k-anon checks won't be impacted because reporting destinations are not checked for k-anon.
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 .
Yes

…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}

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}

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 · 2023-09-26T19:42:58Z

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 · 2023-10-02T22:31:51Z

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.

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}

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

chromium-wpt-export-bot mentioned this issue Jul 25, 2023

Fenced frames: Add reporting to custom destination urls [1/N] web-platform-tests/wpt#41167

Merged

qingxinwu mentioned this issue Aug 21, 2023

Spec: macro reporting support #762

Merged

rdgordon-index mentioned this issue Sep 19, 2023

clarification re: OpenRTB macro substitution capabilities #817

Open

dchristian-ias mentioned this issue Nov 27, 2023

Loss of runtime data for dynamic creatives #931

Open

ajvelasquezgoog mentioned this issue Dec 6, 2023

Passing information to a 3rd Party measurement service during Ad rendering #926

Open

blu25 mentioned this issue Apr 16, 2024

Specification review for fenced frames w3ctag/design-reviews#838

Open

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Supporting creative macros in FLEDGE #477

Supporting creative macros in FLEDGE #477

sewoomg commented Mar 7, 2023 •

edited

TheTamFamily commented Mar 27, 2023

sewoomg commented Apr 4, 2023 •

edited

sewoomg commented Apr 26, 2023

ajvelasquezgoog commented May 19, 2023 •

edited

sewoomg commented Jun 2, 2023

dmdabbs commented Jun 4, 2023 •

edited

ajvelasquezgoog commented Jun 5, 2023 •

edited

TheTamFamily commented Jun 22, 2023

keweigegoog commented Jul 18, 2023

gtanzer commented Aug 2, 2023 •

edited

thegreatfatzby commented Aug 24, 2023

ajvelasquezgoog commented Aug 29, 2023

thegreatfatzby commented Sep 26, 2023

thegreatfatzby commented Oct 2, 2023

Supporting creative macros in FLEDGE #477

Supporting creative macros in FLEDGE #477

Comments

sewoomg commented Mar 7, 2023 • edited

Context

Proposal

Example

TheTamFamily commented Mar 27, 2023

sewoomg commented Apr 4, 2023 • edited

sewoomg commented Apr 26, 2023

ajvelasquezgoog commented May 19, 2023 • edited

sewoomg commented Jun 2, 2023

dmdabbs commented Jun 4, 2023 • edited

ajvelasquezgoog commented Jun 5, 2023 • edited

TheTamFamily commented Jun 22, 2023

keweigegoog commented Jul 18, 2023

gtanzer commented Aug 2, 2023 • edited

thegreatfatzby commented Aug 24, 2023

ajvelasquezgoog commented Aug 29, 2023

thegreatfatzby commented Sep 26, 2023

thegreatfatzby commented Oct 2, 2023

sewoomg commented Mar 7, 2023 •

edited

sewoomg commented Apr 4, 2023 •

edited

ajvelasquezgoog commented May 19, 2023 •

edited

dmdabbs commented Jun 4, 2023 •

edited

ajvelasquezgoog commented Jun 5, 2023 •

edited

gtanzer commented Aug 2, 2023 •

edited