Macro Support for FLEDGE creatives

[av-sherman]

We’d like to request a feature to be supported for FLEDGE Original Trials that allows modifying the rendering URL inside the Fenced Frame. This feature request is intended to cover the period of the Origin Trials only.

Example API: deprecatedURLToURN(originalUrn, newUrl) -> newUrn

Rationale:

Macros are a common mechanism for passing runtime data to creatives for use in rendering. An example flow is where an advertiser places text (ex: "%%HEIGHT%%") in their creative and the SSP substitutes this with relevant information (ex: the ad slot height) prior to rendering the creative. Google's ads products support various macros, with one set of examples found at https://support.google.com/admanager/answer/2376981 – usages include size, ad unit, URL, GDPR, and more. There are also commonly-used macros established by industry frameworks, such as ${GDPR}, ${GDPR_CONSENT_XXXXX}, and ${US_PRIVACY}.

Macro substitution fundamentally breaks with FLEDGE – the allowed creative mutations are very limited and fenced frame rendering means that creatives render without access to the publisher’s page or information.

The navigator.deprecatedURNToURL API supported by the FLEDGE OT spec allows the retrieval of the underlying URL for the winning FLEDGE creative, which would allow applying macro substitutions to the creative URL. With the current spec, however, this modified URL could only be rendered in an IFrame and not a Fenced Frame.

We propose that the browser support a debug API that allows loading the modified rendering URL inside the Fenced Frame (and in particular invoking the same reporting API as if deprecatedURNToURL had never been called). This would be a mechanism to continue to support macro substitution during the Origin Trials, while the ads industry adjusts to a new world where macro substitution is no longer possible.

[jkarlin]

Hi there, thanks for filing the report!

With the current spec, however, this modified URL could only be rendered in an IFrame and not a Fenced Frame.

Can you point me to where this is written? We need to update that. You can actually load a plaintext url in a Fenced Frame, and put it in opaque-ads mode. Which is what I recommend that you do. e.g., first call deprecatedURNToURL to get the plaintext URL, modify it as needed, and then load it in <fencedframe mode="opaque-ads" src=your_macro_substituted_url>.

[jeffkaufman]

@jkarlin Sorry, you're right that "this modified URL could only be rendered in an IFrame and not a Fenced Frame" is incorrect. The motivation for this proposal, though, is the "invoking the same reporting API as if deprecatedURNToURL had never been called" bit.

Specifically, rendering a plaintext url in a fencedframe won't allow the APIs in https://github.com/WICG/turtledove/blob/main/Fenced_Frames_Ads_Reporting.md (ex: window.fence.reportEvent), to work, because the browser will not know which FLEDGE auction they refer to.

[jkarlin]

Ah, I see. You lose the metadata associated with the oapque url when translating. Thanks for the clarification.

[JensenPaul]

This seems like a reasonable need as it enables experimentation with Fenced Frames and the reporting APIs therein as @jeffkaufman's comment mentions. This seems like something that’s permissible during the OT phase while converting URNs to URLs is already facilitated by the navigator.deprecatedURNToURL() API. Two questions:

1. Allowing replacement of the entire URL seems overly powerful; a bidder might be unpleasantly surprised if a seller replaced their winning ad creative URL with that of another ad creative URL. What if we limited this to only macro substitutions and only when the pattern to replace either started with “${“ and ended with “}” (and didn’t contain other “{“ or “}” instances), or started and ended with “%%” (and didn’t contain other “%%” instances)? For example the API might look like: navigator.deprecatedReplaceInURN(urn, {'${X}': '1', '%%Y%%': '2'})

2. How do you expect this to work with component ads? Perhaps it could perform the macro substitution on the component ad URLs also?

[av-sherman]

An API as you describe that formally supports macro substitution should work for this feature request. Also supporting these substitutions for component ads would be important as well.

Thanks.

[brusshamilton]

Do you need the API to support replacing "${"/"}" delimited sequences within URL paths (not query or fragment strings)? Supporting that case is more complicated due to how URL parsing works -- the URL parsing spec (https://url.spec.whatwg.org/#url-parsing) specifies that the '{' and '}' characters will be percent encoded inside paths but not inside query or fragment strings.

[av-sherman]

The spec for the ${GDPR_CONSENT_XXXXX} and similar macros indicates that they are used as URL parameters, though it's possible they are being used in other parts of the URL.

Note also that macro text isn't necessarily static and can include dynamic information -- the actual replacement logic that would be most useful would be closer to a regex. E.g., something that can handle &gdpr_consent=${GDPR_CONSENT_123}, &gdpr_consent=${GDPR_CONSENT_777}, etc.

[brusshamilton]

navigator.deprecatedReplaceInURN has now been implemented in Chrome 103.

[jeffkaufman]

Demo pages showing that it works: first https://www.trycontra.com/test/td/join-replace.html and then https://www.jefftk.com/test/td/auction-replace.html

[gtanzer]

Just so you all know, as of M112 deprecatedReplaceInURN and deprecatedURNToURL also work with fenced frame configs. (The method name is the same; you pass a config in the same slot instead of a urn.)

[timphsieh-google]

Do you know how long will deprecatedReplaceInURN() be supported?

[rahulkooverjee-google]

I’d like to follow up on @timphsieh's comment and ask if the Chrome team would be able to support deprecatedReplaceInURN until Fenced Frame enforcement in 2026.

Rationale

We believe that supporting macro substitution at 3PCD and through 2026 will help the industry better navigate the transition period, given there are a number of key advertising use cases that rely on macro substitution today, without materially impacting the privacy model.

Use cases for macro substitution
As @av-sherman noted, macro substitution is a common mechanism for passing data to creatives for use in rendering.

Perhaps the most significant use case is regulatory consent requirements, where macro substitution is commonly used within industry frameworks to pass user consent information to ad tech vendors (e.g. the ${GDPR_CONSENT_XXXXX} macro). Transitioning the entire industry to a different framework will take time, which may jeopardize ecosystem readiness for cookie deprecation.

There are other important use cases for macro substitution too - for example buyers may use information retrieved through macro substitution (such as ad size, or even contextual information) to optimize creative asset selection at render time. While there are alternative approaches that may enable this use case, it’d require that both sellers and buyers transition away from the existing, commonly used, and well optimized approach and it’s unclear what benefit that would bring (see below).

Why we believe 2026 should be okay
We appreciate that one of the privacy goals of the Protected Audience API and the requirement that ads render in a Fenced Frame is to prevent communication between the page and the creative. However, given that Fenced Frames will not be required until 2026, it will be the case that communication between the page and the creative is possible - for example via a postMessage() into an iFrame.

Therefore, it seems consistent to also allow for macro substitution via deprecatedReplaceInURN until Fenced Frame rendering is required.

[JensenPaul]

In May 2022 Chrome added support for deprecatedReplaceInURN to address a number of different transitional issues that arose as Protected Audiences was adopted. The original ask is detailed in this issue. Macro replacement in ad creative URLs was a practice that predates Protect Audiences. The ask for this API was originally only for the duration of the Protected Audience origin trial.

The API was also later found to help ease the transition to Protected Audience in other ways. For example, as adtechs work to adopt passing ad width and height into Protected Audience using the new ad sizes API, deprecatedReplaceInURN allowed prototyping this macro replacement before the new API was adopted, which helped avoid an extra network roundtrip.

We’ve been thinking more about when to deprecate this feature as it facilitates user identity flowing into the ad rendering frame, which is something that Fenced Frames seeks to avoid. However it turns out that deprecatedReplaceInURN aides in Fenced Frame adoption because it can facilitate some legacy instances where it’s useful to pass contextual information into the ad rendering frame. Without these legacy instances addressed by deprecatedReplaceInURN, adtech might prefer to render ads in iframes (thus delaying Fenced Frame adoption) and pass this information in via postMessage, which Fenced Frames don’t allow. So, while iframe rendering is allowed until 2026, it makes sense to allow deprecatedReplaceInURN to be used.

For the reasons above, we will continue to support deprecatedReplaceInURN until at least 2026.