docs(creative): translateUniversalMacros helper guide (helper 2/2: docs)

[BaiyuScope3]

Adds an "Implementing translation with the SDK" example under docs/creative/universal-macros.mdx so sales agents have a concrete pattern for the universal-macro rewrite the spec requires.

Shows the @adcp/sdk translateUniversalMacros(pixel_url, mapping) helper:

• value arm (literal, RFC-3986 percent-encoded) vs native arm (ad-server token, inserted raw)
• parameters with unmapped macros are dropped — inspect unmapped_macros so a forgotten consent macro isn't silently lost
• already-minted params pass through untouched
• suspect_native_values flags a value mistakenly shaped like a native token
• only query-parameter values are translated

Documents the helper shipping in adcontextprotocol/adcp-client#2263. Pure docs — no schema or behavior change.

🤖 Generated with Claude Code

[aao-release-bot]

Clean docs addition. Right call to anchor the SDK example as an h4 under "Sales Agent Processing" rather than a new top-level section — translation is a step in that flow, not a parallel concept.

Things I checked

• Macro coherence. Every macro in the example ({MEDIA_BUY_ID}, {PACKAGE_ID}, {CACHEBUSTER}, {DEVICE_ID}) is in the macro tables (universal-macros.mdx:44-48, 106). The consent macros the prose tells you to inspect ({GDPR_CONSENT}, {US_PRIVACY}) are in the Privacy table (L58-59). No invented names.
• GAM token consistency. The native translations in the example — {CACHEBUSTER} → %%CACHEBUSTER%%, {DEVICE_ID} → %%ADVERTISING_IDENTIFIER_PLAIN%% — match the existing "Translates platform macros" list verbatim (L522-523). No drift between the new example and the prose it sits under.
• No wire surface. Nothing under static/schemas/source/** touched. Pure prose documenting a client-side @adcp/sdk helper. patch changeset is the right shape for a docs-only addition.
• Heading hierarchy. h4 #### Implementing translation with the SDK nests correctly under the h3 ### 3. Sales Agent Processing and lands before ### 4. Impression Time.
• Security framing is sound. "value entries are RFC-3986 percent-encoded, so a value containing reserved characters can't break or inject into the URL" is the correct reason to encode — and the doc draws the native/value distinction precisely (native left raw so the ad server still recognizes the token). Good instinct documenting the injection rationale rather than just the mechanic.

Follow-ups (non-blocking — file as issues)

• The section documents translateUniversalMacros as shipping in adcontextprotocol/adcp-client#2263. If this doc merges before that helper publishes, the example references an import that doesn't resolve. Worth gating the merge on the SDK release, or noting the minimum @adcp/sdk version inline.

LGTM. Follow-up noted.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
adcp	🟢 Ready	View Preview	Jun 22, 2026, 10:00 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[aao-release-bot]

Clean docs addition. Documents an SDK helper that maps universal macros to either a native ad-server token or a percent-encoded value — the right shape for the rewrite the spec already describes in section 3.

Things I checked

• Coherence with the existing page. The example mapping at universal-macros.mdx:537-543 matches what section 3 already claims: {MEDIA_BUY_ID} → mb_spring_2025, {PACKAGE_ID} → pkg_ctv_prime, {CACHEBUSTER} → %%CACHEBUSTER%% (GAM), {DEVICE_ID} → %%ADVERTISING_IDENTIFIER_PLAIN%% (GAM). No drift between the prose and the worked example.
• Example self-consistency. Four params, all four macros mapped → dropped_params: [] and unmapped_macros: [] are correct for the input URL. The annotated url output reflects native tokens left raw and value arms substituted in place.
• Security framing is right. The doc leads with the load-bearing distinction: value arms are RFC-3986 percent-encoded (can't break or inject into the URL), native arms inserted verbatim so the ad server still recognizes them. The suspect_native_values callout flags a value shaped like a native token — the most likely mapping mistake.
• The consent callout earns its bold. Telling agents to inspect unmapped_macros so a forgotten {GDPR_CONSENT} / {US_PRIVACY} isn't silently dropped is the right warning to surface, and it ties into the Privacy Compliance section lower on the page.
• No wire surface. docs/creative/** guide, not docs/reference/** or static/schemas/source/** — no changeset required, no schema-vs-docs audit triggered.

Follow-ups (non-blocking — file as issues)

• The documented return shape (url, dropped_params, unmapped_macros, suspect_native_values) lives in adcp-client#2263, a separate repo this diff can't validate against. Worth a quick check that the field names and arm names (value / native) match the shipped helper signature once that PR lands, so the guide doesn't drift from the API on day one. Documenting helper 2/2 before helper 1/2 has merged is a reasonable order — just confirm the signatures agree.

LGTM. Follow-up noted.

[aao-release-bot]

Clean docs addition — gives sales agents a concrete translateUniversalMacros pattern for the rewrite the spec already requires. Right shape: it documents the helper's contract (encoding, drop semantics, consent surfacing) rather than re-explaining the macro table.

Things I checked

• Macro coherence. Every macro in the example resolves against this page's own table: {MEDIA_BUY_ID}/{PACKAGE_ID} (identity), {CACHEBUSTER}/{DEVICE_ID} (runtime). The GAM native tokens %%CACHEBUSTER%% and %%ADVERTISING_IDENTIFIER_PLAIN%% match the existing rewrite example at L522–523 — no invented syntax.
• Consent macro names. {GDPR_CONSENT} and {US_PRIVACY} cited in the dropped_consent_macros note exist in the privacy table at L58–L59. No drift.
• Privacy framing is load-bearing. The "inspect dropped_consent_macros so a forgotten mapping doesn't silently ship a consent-degraded pixel" line is the right emphasis given this page's own GDPR/CCPA section (L562+).
• No wire surface. Single file, docs/creative/universal-macros.mdx, 54 net additions. No static/schemas/source/**, no docs/reference/** — changeset correctly omitted.

Follow-ups (non-blocking — file as issues)

• The documented behavior (RFC-3986 encoding, suspect_native_values regex shapes, unmapped-param drop) is the contract of the helper shipping in adcp-client#2263. Docs and helper need to stay in sync — if the helper's return shape changes during review there, this page drifts. Worth confirming both land together.

LGTM.