Advertising DSP Macros

Last update: February 9, 2025

CREATED FOR:

  • User

A macro is a short command or shorthand for an instruction and usually follows the format ${MACRO_NAME}. Macros included in creative code or click-through URLs expand into a longer code string that the ad server can understand. The DSP ad server executes macros when the ad is served or clicked.

Ad server macros are useful for passing important information to DSP or to third-party ad servers. Macros are most commonly used during trafficking of third-party and custom creative code or metadata (such as third-party pixels).

You can manually insert a macro anywhere, such as in a VAST tag, in any URL, or in a DSP or third-party event pixel. However, each DSP client and partner has a different ad tag format, and the macros should be inserted in different spots in the tag accordingly. Each time you work with a new client or partner, ask them for documentation on where to insert the macros in their ad tags that DSP traffics.

General Tracking Macros

Use general tracking macros across all ad and tag types to pass back specific data, as required.

MacroReplacement DescriptionType
${TM_ACCOUNT_ID}The account ID.integer
${TM_AD_ID}The ad key (adKey).string
${TM_AD_ID_NUM}The ad ID.integer
${TM_ADVERTISER_ID}The advertiser ID.integer
${TM_CAMPAIGN_ID}The campaign key.string
${TM_CAMPAIGN_ID_NUM}The campaign ID.integer
${TM_CLICK_URL}The redirect URL, which enables ad servers to track and count ad clicks. When the ad is served, if the user clicks it, the macro is activated and the click is recorded and counted for reporting purposes.string
${TM_CLICK_URL_URLENC}The encoded redirect URL, which enables ad servers to track and count ad clicks. When the ad is served, if the user clicks it, the macro is activated and the click is recorded and counted for reporting purposes. Don’t use this macro unless you are creating third-party ads and your vendor requires URL encoding.string
${TM_FEED_ID}The key for the media placement (feedKey).string
${TM_FEED_ID_NUM}The ID for the media placement.integer
${TM_MACRO_PLACEMENT_SITE_KEYThe site key for the placement. Required for AppsFlyer click trackers for mobile app install ads.string
${TM_PLACEMENT_ID}The placement key (cpKey).string
${TM_PLACEMENT_ID_NUM}The placement ID.integer
${TM_RANDOM}Cachebuster: a random number between 1 and 1000000.long
${TM_SESSION_ID}The ID of the session, which corresponds to a single retrieval of the ad tag.string
${TM_SITE_DOMAIN_URLENC}The page subdomain parsed from the URL in the bid request; URL-encoded. Not supported for in-banner, click-to-play ads.string
${TM_SITE_NAME}The site name for the placement.string
${TM_SITE_URL_URLENC}The URL passed in the bid request; URL-encoded. Not supported for in-banner, click-to-play ads.string
${TM_SITE_ID_NUM}The site ID for the placement.integer
${TM_TIMESTAMP}The Unix timestamp indicating the number of seconds elapsed since midnight (00:00 UTC) on 1 January 1970.long
${TM_VIDEO_DURATION}The duration of the ad video in seconds.integer

Mobile-Specific Macros

MacroReplacement DescriptionType
${CS_PLATFORM_ID}

(ComScore) The platform ID, which corresponds to the device’s operating system:

  • ios = Apple iOS
  • android = Google Android
  • windows = Windows Mobile
  • blackberry = Blackberry
  • other when the platform is none of the above
varchar(50)
${CS_DEVICE_MODEL}(ComScore) The device model name, URL-encoded.string
${CS_IMPLEMENTATION_TYPE}

(ComScore) The environment in which the ad was served:

  • a = mobile application
  • b = mobile website
string (a or b)
${NS_PLATFORM_ID}

(Nielsen) The platform ID, which corresponds to the device’s operating system:

  • ios= Apple iOS
  • android = Google Android
  • windows = Windows Mobile
  • blackberry = Blackberry
  • other when the platform is none of the above
string
${NS_DEVICE_GROUPING}

(Nielsen) The device type on which the ad was viewer:

  • TAB = tablet
  • PHN = mobile
  • computer = computer
string
${UOO}

(Nielsen) Whether or not the user has opted out of ad tracking:

  • 1 (DNT flag = 1) = the user has opted out of ad tracking
  • 0 (DNT flag = 0) = the user has opted in to ad tracking
integer (0 or 1)
${TM_BUNDLE}The iOS or Android app store bundle ID. Examples: com.zynga.wwf2.free or id804379658string
gdpr=${GDPR_ENFORCED}&gdpr_consent=${GDPR_CONSENT}

gdpr=${GDPR_ENFORCED} indicates if the bidder determines that the bid request comes from the European Union origin and requires GDPR enforcement:

  • 1 = GDPR should be enforced
  • 0 = GDPR should not be enforced

gdpr_consent=${GDPR_CONSENT} is the consent value passed from the supply partner in the inbound bid request:

  • In most cases, this is a base64url-encoded consent string, or daisybit (example: BN5lERiOMYEdiAKAWXEND1HoSBE6CAFAApAMgBkIDIgM0AgOJxAnQA)
  • 0 = no consent
  • 1 = consent
daisybit or integer