adobe / adobe/xdm

Generalize paid-media-creative variants for Google Ads customizers (deprecate localeVariants)

Open
#2,178 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
266
Forks
380
Avg merge
5d 8h
Merged PRs (30d)
9

Description

## Background

[PR #2174](https://github.com/adobe/xdm/pull/2174) added `xdm:localeVariants` to the `paid-media-creative` datatype, modeled on Meta's `asset_feed_spec` `language_label` (multi-language ads).

During connector implementation review, it surfaced that **Google Ads `CustomizerAttribute` substitution produces materially different rendered headlines/bodies that are not keyed by locale**. Example: a headline `Get {CUSTOMIZER.discount} on Adobe Creative Cloud Subscription` with a `discount` attribute linked at the ad-group-criterion level can resolve to `5%`, `10%`, `15%`, `20%` across different keywords. Each of these is a distinct served impression that downstream consumers (CJA Content Analytics → feature extraction → LLM sentiment analysis) need to snapshot independently.

Storing only the unresolved template string loses fidelity for the analytics pipeline.

## Proposed Change

* Soft-deprecate `xdm:localeVariants` on the `paidMediaCreative` definition (`meta:status: deprecated` + description prefix `"Deprecated: Use xdm:variants instead..."`). Connector has not yet implemented populating this field, so deprecation cost is minimal.
* Add a more general `xdm:variants` array. Each variant carries:
* `xdm:variantID` — stable identifier
* `xdm:language` — BCP 47 tag, optional (set for Meta-style multi-language variants)
* `xdm:customizers[]` — optional, list of resolved customizer attributes (`name`, `type`, `value`, `scope`). `scope` enum: `customer | account | campaign | adGroup | adGroupCriterion | asset | other`
* Per-variant overrides of `title`, `body`, `callToAction`, `destinationURL`, `displayURL`, `trackingURLs`, `assets`
* Add new `creativeCustomizer` and `creativeVariant` sub-definitions.
* Migrate `paid-media-creative.example.4.json` from `xdm:localeVariants` to `xdm:variants`.
* Add `paid-media-creative.example.5.json` demonstrating Google Ads customizer expansion (4 rendered variants for 5 / 10 / 15 / 20 % discount).

## Network Coverage

| Ad network | Variant signal | Stored in |
|---|---|---|
| Meta multi-language ads | `language_label` | `xdm:language` |
| Google Ads CustomizerAttribute | resolved attribute name/value/scope | `xdm:customizers[]` |
| Meta + Google with both axes | both | both fields populated |
| TikTok / Snapchat / LinkedIn | locale and/or template substitution | same shape |

## Reference

* [Google Ads – CustomizerAttribute resolution & RSA customization](https://developers.google.com/google-ads/api/docs/ads/customize-responsive-search-ads)
* [Meta Marketing API – Multi-Language Ads](https://developers.facebook.com/docs/marketing-api/multi-language-ads/)

## Related

* Original PR: #2174
* Predecessor issue: #2173
* Internal Adobe Jira: AN-451840 (predecessor AN-451211, design AN-450480)

Contributor guide

Open the contributing guide

Research direction

Start by inspecting the paid-media-creative definition and the existing paid-media-creative.example.4.json. Deprecate xdm:localeVariants, add the creativeCustomizer and creativeVariant sub-definitions and xdm:variants, then migrate example 4 and add paid-media-creative.example.5.json with four Google Ads discount variants. Done means both Meta language variants and Google customizer values are represented by the new shape.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
backend-api-design, data
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.