Universal Macros

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

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

// In creative logic
if (GDPR == 1 && GDPR_CONSENT == '') {
  // No consent - don't load tracking pixels
} else {
  // Load 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"
    }
  }
}

{
  "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}"
    }
  }
}

{
  "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={COLLECTION_NAME}&cb={CACHEBUSTER}"
    }
  }
}

{
  "creative_id": "cr_product_carousel",
  "format_id": {
    "agent_url": "https://creative.retailer.com/adcp",
    "id": "product_carousel"
  },
  "catalogs": [{
    "catalog_id": "gmc-primary",
    "type": "product",
    "content_id_type": "gtin",
    "tags": ["summer"]
  }],
  "assets": {
    "impression_pixel": {
      "url": "https://track.brand.com/imp?buy={MEDIA_BUY_ID}&catalog={CATALOG_ID}&item={GTIN}&cb={CACHEBUSTER}",
      "url_type": "tracker_pixel"
    },
    "click_tracker": {
      "url": "https://track.brand.com/click?buy={MEDIA_BUY_ID}&catalog={CATALOG_ID}&item={GTIN}",
      "url_type": "tracker_pixel"
    }
  }
}

{
  "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
}

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

import { translateUniversalMacros } from '@adcp/sdk';

const mapping = {
  // AdCP identifiers the agent knows at media-buy creation → concrete values
  '{MEDIA_BUY_ID}': { value: 'mb_spring_2025' },
  '{PACKAGE_ID}': { value: 'pkg_ctv_prime' },
  // Runtime macros → the ad server's native syntax (Google Ad Manager shown)
  '{CACHEBUSTER}': { native: '%%CACHEBUSTER%%' },
  '{DEVICE_ID}': { native: '%%ADVERTISING_IDENTIFIER_PLAIN%%' },
};

const { url, dropped_params, unmapped_macros, dropped_consent_macros, suspect_native_values } =
  translateUniversalMacros(
    'https://track.brand.com/imp?buy={MEDIA_BUY_ID}&pkg={PACKAGE_ID}&cb={CACHEBUSTER}&device={DEVICE_ID}',
    mapping,
  );

// url:
//   https://track.brand.com/imp?buy=mb_spring_2025&pkg=pkg_ctv_prime&cb=%%CACHEBUSTER%%&device=%%ADVERTISING_IDENTIFIER_PLAIN%%
// dropped_params: []           (every macro was mapped)
// unmapped_macros: []
// dropped_consent_macros: []   (no consent macro was dropped)
// suspect_native_values: []    (no value entry looks like a native token)

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

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

// 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();
}

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

// 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);
}

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

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

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

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

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

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

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