Universal Macros - AdCP - Ad Context Protocol

Universal macros enable buyers to include dynamic tracking data in their creatives without needing to know each publisher’s ad server implementation details. Macros are placeholders that get replaced with actual values at impression time.

Overview

When you provide creative assets to AdCP, you can include universal macro placeholders in:

Impression tracking URLs
Click tracking URLs
VAST tracking events
Landing page URLs

Example:

https://track.brand.com/imp?
  campaign={MEDIA_BUY_ID}&
  creative={CREATIVE_ID}&
  device={DEVICE_ID}&
  cb={CACHEBUSTER}

At impression time, this becomes:

https://track.brand.com/imp?
  campaign=mb_spring_2025&
  creative=cr_video_30s&
  device=ABC-123-DEF&
  cb=87654321

Available Macros by Format

Different creative formats support different macros. Use list_creative_formats to see which macros are available for each format.

Common Macros (All Formats)

Macro	Description	Example Value
`{MEDIA_BUY_ID}`	Your AdCP media buy identifier	`mb_spring_2025`
`{PACKAGE_ID}`	Your AdCP package identifier	`pkg_ctv_prime`
`{CREATIVE_ID}`	Your AdCP creative identifier	`cr_video_30s`
`{CACHEBUSTER}`	Random number to prevent caching	`87654321`
`{TIMESTAMP}`	Unix timestamp in milliseconds	`1704067200000`
`{CLICK_URL}`	Publisher’s click tracking URL	(auto-inserted by sales agent)

Privacy & Compliance Macros

Critical for regulatory compliance - Use these to respect user privacy choices in your creative logic.

Macro	Description	Example Value
`{GDPR}`	GDPR applicability flag	`1` (applies), `0` (doesn’t apply)
`{GDPR_CONSENT}`	IAB TCF 2.0 consent string	`CPc7TgPPc7TgPAGABC...`
`{US_PRIVACY}`	US Privacy (CCPA) string	`1YNN`
`{GPP_STRING}`	Global Privacy Platform consent string	`DBABMA~1...`
`{LIMIT_AD_TRACKING}`	Limit Ad Tracking enabled	`1` (limited), `0` (allowed)

Example - Privacy-aware tracking:

// In creative logic
if (GDPR == 1 && GDPR_CONSENT == '') {
  // No consent - don't load tracking pixels
} else {
  // Load tracking
}

Device & Environment Macros

Macro	Description	Example Value
`{DEVICE_TYPE}`	Device category	`mobile`, `tablet`, `desktop`, `ctv`, `dooh`
`{OS}`	Operating system	`iOS`, `Android`, `tvOS`, `Roku`
`{OS_VERSION}`	OS version	`17.2`, `14.0`
`{DEVICE_MAKE}`	Device manufacturer	`Apple`, `Samsung`, `Roku`
`{DEVICE_MODEL}`	Device model	`iPhone15,2`, `Roku Ultra`
`{USER_AGENT}`	Full user agent string	`Mozilla/5.0 ...`
`{APP_BUNDLE}`	App bundle ID (domain or numeric)	`com.publisher.app`, `123456789`
`{APP_NAME}`	Human-readable app name	`Publisher News App`

Geographic Macros

Macro	Description	Example Value
`{COUNTRY}`	ISO 3166-1 alpha-2 country code	`US`, `GB`, `CA`, `FR`, `JP`, `AU`
`{REGION}`	State/province/region code	`NY`, `CA` (US states), `ON` (Canada), `IDF` (France), `NSW` (Australia)
`{CITY}`	City name	`New York`, `London`, `Tokyo`, `Sydney`
`{ZIP}`	Postal code	`10001` (US), `SW1A 1AA` (UK), `75001` (France), `100-0001` (Japan)
`{DMA}`	Nielsen DMA code (US TV markets)	`501` (New York), `803` (Los Angeles)
`{LAT}`	Latitude	`40.7128`, `51.5074`, `35.6762`
`{LONG}`	Longitude	`-74.0060`, `-0.1278`, `139.6503`

Identity Macros

Macro	Description	Example Value
`{DEVICE_ID}`	Mobile advertising ID (IDFA/AAID)	`ABC-123-DEF-456`
`{DEVICE_ID_TYPE}`	Type of device ID	`idfa`, `aaid`

Web Context Macros

For web-based inventory:

Macro	Description	Example Value
`{DOMAIN}`	Domain where ad is shown	`nytimes.com`
`{PAGE_URL}`	Full page URL (encoded)	`https%3A%2F%2F...`
`{REFERRER}`	HTTP referrer URL	`https://google.com`
`{KEYWORDS}`	Page keywords (comma-separated)	`business,finance,tech`

Placement & Position Macros

Macro	Description	Example Value
`{PLACEMENT_ID}`	Global Placement ID (IAB standard)	`12345678`
`{FOLD_POSITION}`	Position relative to fold (display)	`above_fold`, `below_fold`
`{AD_WIDTH}`	Ad slot width	`300`, `728`
`{AD_HEIGHT}`	Ad slot height	`250`, `90`

Video Content Macros

For video formats with content context:

Macro	Description	Example Value
`{VIDEO_ID}`	Content video identifier	`vid_12345`
`{VIDEO_TITLE}`	Content video title	`Breaking News Story`
`{VIDEO_DURATION}`	Content duration in seconds	`600`
`{VIDEO_CATEGORY}`	IAB content category	`IAB1` (Arts & Entertainment)
`{CONTENT_GENRE}`	Content genre	`news`, `sports`, `comedy`
`{CONTENT_RATING}`	Content rating	`G`, `PG`, `TV-14`
`{PLAYER_WIDTH}`	Video player width	`1920`
`{PLAYER_HEIGHT}`	Video player height	`1080`

Video Ad Pod Macros

For video ads in commercial breaks:

Macro	Description	Example Value
`{POD_POSITION}`	Position within ad break	`1`, `2`, `3`
`{POD_SIZE}`	Total ads in this break	`3`
`{AD_BREAK_ID}`	Unique ad break identifier	`break_mid_1`

Note: Video formats also support all IAB VAST 4.x macros like [CACHEBUSTING], [TIMESTAMP], [DOMAIN], [IFA], etc. These work natively in VAST XML.

AXE Integration

Macro	Description	Example Value
`{AXEM}`	AXE contextual metadata (encoded blob)	`eyJjb250ZXh0IjoiLi4uIn0=`

Note: Publisher-specific custom macros may be defined in individual creative format specifications as extra supported macros.

Usage Examples

Video Creative with Tracking

{
  "creative_id": "cr_video_30s",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "video_30s_vast"
  },
  "assets": {
    "vast_xml": {
      "asset_type": "vast",
      "delivery_type": "inline",
      "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<VAST version=\"4.2\">\n  <Ad>\n    <InLine>\n      <Impression><![CDATA[https://track.brand.com/imp?buy={MEDIA_BUY_ID}&pkg={PACKAGE_ID}&cre={CREATIVE_ID}&device={DEVICE_ID}&domain={DOMAIN}&cb=[CACHEBUSTING]]]></Impression>\n      <Creatives>\n        <Creative>\n          <Linear>\n            <Duration>00:00:30</Duration>\n            <TrackingEvents>\n              <Tracking event=\"firstQuartile\"><![CDATA[https://track.brand.com/q1?buy={MEDIA_BUY_ID}&cb=[CACHEBUSTING]]]></Tracking>\n              <Tracking event=\"complete\"><![CDATA[https://track.brand.com/complete?buy={MEDIA_BUY_ID}&cb=[CACHEBUSTING]]]></Tracking>\n            </TrackingEvents>\n            <VideoClicks>\n              <ClickThrough><![CDATA[https://brand.com/spring?campaign={MEDIA_BUY_ID}]]></ClickThrough>\n            </VideoClicks>\n            <MediaFiles>\n              <MediaFile delivery=\"progressive\" type=\"video/mp4\" width=\"1920\" height=\"1080\">\n                <![CDATA[https://cdn.brand.com/videos/spring_30s.mp4]]>\n              </MediaFile>\n            </MediaFiles>\n          </Linear>\n        </Creative>\n      </Creatives>\n    </InLine>\n  </Ad>\n</VAST>",
      "vast_version": "4.2"
    }
  }
}

Key Points:

Mix AdCP macros ({MEDIA_BUY_ID}) with VAST macros ([CACHEBUSTING])
AdCP macros use {CURLY_BRACES}
VAST macros use [SQUARE_BRACKETS]
Both work together seamlessly

Display Creative with Tracking

{
  "creative_id": "cr_banner_300x250",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_banner_300x250"
  },
  "assets": {
    "banner_image": {
      "url": "https://cdn.brand.com/banners/spring_300x250.jpg",
      "width": 300,
      "height": 250
    },
    "impression_pixel": {
      "url": "https://track.brand.com/imp?buy={MEDIA_BUY_ID}&pkg={PACKAGE_ID}&cre={CREATIVE_ID}&device={DEVICE_ID}&domain={DOMAIN}&cb={CACHEBUSTER}"
    },
    "landing_url": {
      "url": "https://brand.com/spring?campaign={MEDIA_BUY_ID}"
    }
  }
}

Audio Creative with Tracking

{
  "creative_id": "cr_audio_30s",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "audio_streaming_30s"
  },
  "assets": {
    "audio_file": {
      "url": "https://cdn.brand.com/audio/spring_30s.mp3",
      "duration_ms": 30000
    },
    "impression_tracker": {
      "url": "https://track.brand.com/imp?buy={MEDIA_BUY_ID}&pkg={PACKAGE_ID}&station={STATION_ID}&show={SHOW_NAME}&cb={CACHEBUSTER}"
    }
  }
}

Macro Availability by Inventory Type

Not all macros are available in all inventory types. Check format specifications to see which macros are supported. Important: The columns below represent format types (Display, Video, etc.) which can run in different environments (app vs web). For example:

Display ads in mobile apps have DEVICE_ID (✅*), but display ads on web do not
The ✅* notation means “available in-app contexts only”
Format type + inventory environment determine actual macro availability

Macro Category	Display	Video	Audio	Native	CTV/OTT	DOOH	Mobile App	Mobile Web	Desktop Web
Common	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{MEDIA_BUY_ID}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{PACKAGE_ID}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{CREATIVE_ID}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{CACHEBUSTER}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
Privacy
`{GDPR}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{GDPR_CONSENT}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{US_PRIVACY}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{LIMIT_AD_TRACKING}`	✅*	✅*	✅*	✅*	✅	❌	✅	❌	❌
Identity
`{DEVICE_ID}`	✅*	✅*	✅*	✅*	✅	❌	✅	❌	❌
`{DEVICE_ID_TYPE}`	✅*	✅*	✅*	✅*	✅	❌	✅	❌	❌
Geographic
`{COUNTRY}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{REGION}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{CITY}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{ZIP}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{DMA}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{LAT}/{LONG}`	✅†	❌	❌	✅†	❌	✅	✅†	❌	❌
Device
`{DEVICE_TYPE}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{OS}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{OS_VERSION}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{APP_BUNDLE}`	✅*	✅*	✅*	✅*	✅	❌	✅	❌	❌
`{USER_AGENT}`	✅	✅	✅	✅	✅	❌	❌	✅	✅
Web Context
`{DOMAIN}`	✅	✅	✅	✅	❌	❌	❌	✅	✅
`{PAGE_URL}`	✅	✅	✅	✅	❌	❌	❌	✅	✅
`{REFERRER}`	✅	✅	✅	✅	❌	❌	❌	✅	✅
`{KEYWORDS}`	✅	✅	✅	✅	❌	❌	❌	✅	✅
Placement
`{PLACEMENT_ID}`	✅	✅	✅	✅	✅	✅	✅	✅	✅
`{FOLD_POSITION}`	✅	❌	❌	✅	❌	❌	✅	✅	✅
Video Content
`{VIDEO_ID}`	❌	✅	❌	❌	✅	❌	❌	❌	❌
`{VIDEO_CATEGORY}`	❌	✅	❌	❌	✅	❌	❌	❌	❌
`{CONTENT_GENRE}`	❌	✅	✅	❌	✅	❌	❌	❌	❌
Video Ad Pods
`{POD_POSITION}`	❌	✅	❌	❌	✅	❌	❌	❌	❌
`{POD_SIZE}`	❌	✅	❌	❌	✅	❌	❌	❌	❌
`{AD_BREAK_ID}`	❌	✅	❌	❌	✅	❌	❌	❌	❌

Legend:

✅ = Available
❌ = Not available
✅* = In-app only (not mobile web)
✅† = When location permission granted

Important Notes:

Privacy macros ({LIMIT_AD_TRACKING}, {DEVICE_ID}) may return empty values based on user privacy settings
Geographic macros accuracy varies by publisher’s data capabilities
{PLACEMENT_ID} refers to the IAB Global Placement ID standard

How Macros Work

1. Discovery

Query list_creative_formats to see which macros each format supports:

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "video_30s_vast"
  },
  "type": "video",
  "supported_macros": [
    {
      "macro": "{MEDIA_BUY_ID}",
      "category": "identity",
      "description": "AdCP media buy identifier",
      "required": false,
      "privacy_sensitive": false,
      "example_value": "mb_spring_2025"
    },
    {
      "macro": "{DEVICE_ID}",
      "category": "identity",
      "description": "Mobile advertising ID (IDFA/AAID)",
      "required": false,
      "privacy_sensitive": true,
      "example_value": "ABC-123-DEF-456"
    },
    {
      "macro": "{GDPR}",
      "category": "privacy",
      "description": "GDPR applicability flag",
      "required": true,
      "privacy_sensitive": false,
      "example_value": "1"
    }
  ],
  "vast_macros_supported": true
}

2. Include Macros in Creatives

Add macro placeholders in your tracking URLs using {MACRO_NAME} syntax:

https://track.brand.com/imp?campaign={MEDIA_BUY_ID}&device={DEVICE_ID}

3. Sales Agent Processing

When you create a media buy via create_media_buy, the sales agent:

Replaces AdCP ID macros with your actual IDs:
- {MEDIA_BUY_ID} → mb_spring_2025
- {PACKAGE_ID} → pkg_ctv_prime
- {CREATIVE_ID} → cr_video_30s
Translates platform macros to their ad server’s syntax:
- {CACHEBUSTER} → %%CACHEBUSTER%% (GAM) or {{timestamp}} (Kevel)
- {DEVICE_ID} → %%ADVERTISING_IDENTIFIER_PLAIN%% (GAM)
- {DOMAIN} → %%SITE%% (GAM)
Inserts click trackers automatically into clickable elements
Leaves VAST macros unchanged (for video formats)

4. Impression Time

The publisher’s ad server replaces remaining macros with actual values:

https://track.brand.com/imp?
  campaign=mb_spring_2025&
  device=ABC-123-DEF-456&
  cb=87654321

Best Practices

Use Macros Consistently

Include the same core set of macros across all your creatives:

?buy={MEDIA_BUY_ID}&pkg={PACKAGE_ID}&cre={CREATIVE_ID}&cb={CACHEBUSTER}

This makes your tracking data consistent and easier to analyze.

Check Format Support

Always query list_creative_formats to see which macros are available. Not all formats support all macros.

Combine VAST and AdCP Macros

For video, use both systems together:

VAST macros [CACHEBUSTING], [TIMESTAMP] - for standard video tracking
AdCP macros {MEDIA_BUY_ID}, {DEVICE_ID} - for your campaign tracking

Privacy Compliance

Critical: Always respect user privacy choices in your creative logic. For campaigns serving in the EU:

// Check consent before loading tracking
if (GDPR == 1) {
  if (GDPR_CONSENT && GDPR_CONSENT != '') {
    // User has consented - load tracking pixels
    loadTracking();
  } else {
    // No consent - skip tracking
    console.log('Tracking skipped - no GDPR consent');
  }
} else {
  // GDPR doesn't apply - load tracking
  loadTracking();
}

US Privacy / CCPA Compliance

For US traffic:

// Check US Privacy string
if (US_PRIVACY == '1YYN') {
  // User has opted out - don't sell personal info
  skipPersonalizedTracking();
} else {
  // Load normal tracking
  loadTracking();
}

Device-Level Privacy

Respect Limit Ad Tracking settings:

// Check if device ID is available
if (LIMIT_AD_TRACKING == 1 || DEVICE_ID == '' || DEVICE_ID == '00000000-0000-0000-0000-000000000000') {
  // User has limited tracking - use contextual attribution
  useContextualTracking();
} else {
  // Device ID available
  useDeviceTracking(DEVICE_ID);
}

Privacy Macro Behavior

Empty Values: Privacy-restricted macros return empty strings or zeros:

{DEVICE_ID} → "" or 00000000-0000-0000-0000-000000000000 when LAT enabled
{GDPR_CONSENT} → "" when no consent provided
{IP_ADDRESS} → "" or masked IP when privacy restricted

Always test for empty values before using privacy-sensitive macros.

URL Encoding

No need to URL-encode macro placeholders. The ad server handles encoding of actual values automatically. Example:

❌ WRONG: https://track.com/imp?device=%7BDEVICE_ID%7D
✅ CORRECT: https://track.com/imp?device={DEVICE_ID}

The ad server will URL-encode the actual value when replacing the macro.

Implementation Notes for Sales Agents

This section is for AdCP implementers, not buyers.

Macro Translation Approach

Sales agents must translate universal macros to their ad server’s native syntax. The recommended approach: Option 1: Hard-Code During Trafficking (MVP)

When creating ad server creatives, replace AdCP ID macros with actual values
Translate platform macros to ad server syntax
Creates one creative per line item but is simple and reliable

Option 2: Dynamic Wrapper (Future)

Intercept ad calls and inject values dynamically
More complex but avoids creative duplication

Translation Examples

Google Ad Manager:

{
  '{CACHEBUSTER}': '%%CACHEBUSTER%%',
  '{DEVICE_ID}': '%%ADVERTISING_IDENTIFIER_PLAIN%%',
  '{DEVICE_ID_TYPE}': '%%ADVERTISING_IDENTIFIER_TYPE%%',
  '{DOMAIN}': '%%SITE%%',
  '{VIDEO_ID}': '%%VIDEO_ID%%'
}

Kevel:

{
  '{CACHEBUSTER}': '{{timestamp}}',
  '{DEVICE_ID}': '{{device.ifa}}',
  '{DEVICE_ID_TYPE}': '{{device.ifaType}}',
  '{DOMAIN}': '{{request.domain}}'
}

Xandr Monetize:

{
  '{CACHEBUSTER}': '${CACHEBUSTER}',
  '{DEVICE_ID}': '${DEVICE_APPLE_IDA}',  // or ${DEVICE_AAID}
  '{DOMAIN}': '${DOMAIN}'
}

Click Tracker Insertion

Sales agents must automatically insert click tracking macros into clickable elements: Original creative:

<a href="https://brand.com/product">Click here</a>

After insertion (GAM):

<a href="%%CLICK_URL_UNESC%%https://brand.com/product">Click here</a>

Mapping Storage

Store the mapping between AdCP IDs and ad server IDs for reconciliation:

{
  media_buy_id: "mb_spring_2025",
  ad_server_order_id: "1234567",
  packages: [
    {
      package_id: "pkg_ctv_prime",
      ad_server_line_item_id: "8901234"
    }
  ]
}

Return this in create_media_buy responses and make it queryable for reconciliation.

Creative Formats - Understanding format specifications and discovery
Creative Protocol - How creatives work in AdCP
sync_creatives - Creative management API

​Overview

​Available Macros by Format

​Common Macros (All Formats)

​Privacy & Compliance Macros

​Device & Environment Macros

​Geographic Macros

​Identity Macros

​Web Context Macros

​Placement & Position Macros

​Video Content Macros

​Video Ad Pod Macros

​AXE Integration

​Usage Examples

​Video Creative with Tracking

​Display Creative with Tracking

​Audio Creative with Tracking

​Macro Availability by Inventory Type

​How Macros Work

​1. Discovery

​2. Include Macros in Creatives

​3. Sales Agent Processing

​4. Impression Time

​Best Practices

​Use Macros Consistently

​Check Format Support

​Combine VAST and AdCP Macros

​Privacy Compliance

​GDPR Compliance (EU Traffic)

​US Privacy / CCPA Compliance

​Device-Level Privacy

​Privacy Macro Behavior

​URL Encoding

​Implementation Notes for Sales Agents

​Macro Translation Approach

​Translation Examples

​Click Tracker Insertion

​Mapping Storage

​Related Documentation