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

[ejsuncy]

What this PR does

Generalizes the xdm:localeVariants field added in #2174 to a broader xdm:variants array on the paid-media-creative datatype. Soft-deprecates the original field.

Each variant in xdm:variants enumerates one materially different rendered version of the creative, regardless of what drives the difference:

• Meta Marketing API multi-language ads — set xdm:language (BCP 47). docs
• Google Ads CustomizerAttribute substitution — set xdm:customizers[] (name, type, value, scope). docs
• Both axes — set both fields populated.
• Other networks (TikTok, Snapchat, LinkedIn) — same shape.

Why this is needed

Reviewing #2174 surfaced that Google Ads customizer attributes are not locale-keyed. A headline Get {CUSTOMIZER.discount} on Adobe Creative Cloud Subscription with discount linked at the ad-group-criterion level resolves to distinct rendered headlines (5%, 10%, 15%, 20%) per keyword. CJA Content Analytics needs each of these as its own snapshot for AI feature extraction. The narrower xdm:localeVariants couldn't represent this.

Per Google Ads API docs, only one value resolves per impression (most-specific-wins among customer < campaign < adGroup < adGroupCriterion), but a single creative ID can render with many distinct values across delivery contexts.

Deprecation handling

Following the repo's soft-deprecation pattern (see #2127, #2158):

• xdm:localeVariants description prefixed with "Deprecated: Use xdm:variants instead...".
• meta:status: deprecated added.
• Field still validates — consumers populating it continue to work.
• Connector has not yet implemented populating it, so cost to migrate is minimal.

The deprecated creativeLocaleVariant definition also gets meta:status: deprecated and a description prefix referring users to the new creativeVariant.

Schema additions

• New creativeCustomizer sub-definition. Fields: xdm:name, xdm:type (enum: text | number | price | percent), xdm:value, xdm:scope (enum: customer | account | campaign | adGroup | adGroupCriterion | asset | other).
• New creativeVariant sub-definition. Fields: xdm:variantID, xdm:language (BCP 47, optional), xdm:customizers[] (optional), plus per-variant overrides for xdm:title, xdm:body, xdm:callToAction, xdm:destinationURL, xdm:displayURL, xdm:trackingURLs, xdm:assets.
• New xdm:variants array on paidMediaCreative, referencing creativeVariant.

Examples

• paid-media-creative.example.4.json — migrated from xdm:localeVariants to xdm:variants (en-US / ar-AR / fr-FR).
• paid-media-creative.example.5.json — new, Google Ads customizer case (4 variants for 5% / 10% / 15% / 20% discount, scope adGroupCriterion).

Breaking changes

None. Additive new field plus soft deprecation. Existing examples 1-3 unchanged.

Validation

• npm run validate components/datatypes/paid-media — 15 / 15 examples passing
• npm test — 2390 mocha tests passing
• npm run lint (prettier) — clean

Related

• Predecessor PR: Add locale variants to paid-media-creative datatype #2174 (merged)
• GitHub issue: Generalize paid-media-creative variants for Google Ads customizers (deprecate localeVariants) #2178 (predecessor Add locale/language variants to paid-media-creative datatype #2173)
• Internal Adobe Jira: AN-451840 (predecessor AN-451211, design ticket AN-450480)