Generalize paid-media-creative variants for Google Ads customizers (deprecate localeVariants)
- 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
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