Campaign Macros

A macro is a piece of placeholder code that tells DSP to insert a predetermined value or set of values at a later point, usually when the ad is served. Use one of the following macro formats:

  • Start and end with curly brackets { }, as in {PUB_ID)}
  • Begin with a $ followed by curly brackets, as in ${PUBLISHERID}

DSP automatically inserts macros in 3rd party ad tags (for 3rd party creatives) for known vendors. For unknown vendors, make sure that the appropriate macros are included in the creative.

Supported Macros

DSP supports the following macros:

Macro Syntax Description
Ad ID ${TRAFFICKEDADID} Inserts the ad ID.
Cache Buster ${REQUESTID} Inserts a timestamp or random number to ensure that a browser or proxy server requests a fresh creative on every ad call, rather than serving a previously served creative that remains in the browser’s cache. When you preview and test creatives, DSP replaces the macro with a random number or request ID to ensure that the creative displays properly.
Click Tracking ${CLICKURL} Inserts a click-through URL so that clicking on the ad first directs users to the ad server (to record the click) before redirecting them to the advertiser’s URL specified in the HREF section of the tag. When the user clicks the ad, the macro sends the information to the redirect URL, enabling the platform to track and therefore count that click. Note: This macro can be used with both secure and non-secure creatives.
Click Tracking Double-Encoded ${CLICKURLENCENC} Inserts a double-encoded click tracking URL (see {CLICK_URL} above). Although rare, some vendors require double-encoded macros for click tracking. Note: This macro can be used with both secure and non-secure creatives.
Click Tracking Encoded ${CLICKURLENC} Inserts an encoded click URL for click tracking (see {CLICK_URL} above). Encoding is sometimes needed if the click tracking URL is used as a query parameter in another URL. Note: This macro can be used with both secure and non-secure creatives.
Creative Height ${HEIGHT} The ${HEIGHT} macro will replace with the height of the current impression. For an ad that is 300 pixels wide and 250 pixels tall, the replaced value will be 250.
Creative ID ${LIBRARYADID} Inserts the creative ID.
Creative Width ${WIDTH} The ${WIDTH} macro will replace with the width of the current impression. For an ad that is 300 pixels wide and 250 pixels tall, the replaced value will be 300.
Device Type ${SCREEN_TYPE} The ${SCREEN_TYPE} macro will be replaced with the type of device that the creative is being served on. The ${SCREEN_TYPE} macro will return PC, Tablet, Phone, or Unknown to match what is available in the targeting UI.
Domain ${DOMAIN} The ${DOMAIN} macro will be replaced with the domain of the current impression. Exposing the domain will help users recognize the site the ad was served under, such as yahoo.com, dmv.ca.gov, or bt.ca. Note: The ${DOMAIN} macro includes the site’s top-level domain (such as .com, .net, or .uk). The ${DOMAIN} macro also captures App_Name for InApp traffic.
HTML5 Landing Page URL ${LANDING_URL} Inserts the encoded landing page URL for HTML5 creatives if there are no click trackers defined. If a single click tracker is present, this macro value is replaced with an empty string. Note: For HTML5 display creatives only.
Is Preview ${IS_PREVIEW} The $IS_PREVIEW macro was created by third party vendors Integral Ad Sciences and Doubleverify as a solution to the issues that brand safety blocking tags present. When you add the macro value to the ad tag, the creative returns a response and DSP successfully previews and audits the creative.
Line ID ${PLACEMENTID} Inserts the advertiser line item ID. This enables advertisers to track and gather information on the line, based on the ID.
Order ID / Campaign ID ${ORDERID} Inserts the campaign ID (campaign = order).
Page URL ${PAGE_URL} Complete URL of the page being served, and any path attributes. This should not contain POST information that happens to be in the URL.
Page URL Encoded ${PAGE_URL_ENC} The same as {PAGE_URL} but encoded.
Publisher ID / Exchange ID ${PUBLISHERID} Inserts the exchange ID. Each exchange has a unique ID.
Sub-Domain ${SUB_DOMAIN} The ${SUB_DOMAIN} macro will be replaced with the complete sub-domain of the current impression. The sub-domain is the string that comes before the domain and top-level domain. For Yahoo domains, this would include sports, finance, and news. Deeper sub-domains can include multiple values, such as premium.advertising or oscar.movies.

Supported Legacy Macros

Macros that start with a $ were added more recently, and in some cases, there are both older and newer macros that have the same functionality. However, to maintain backward compatibility, both macros are supported. (In the example above, {PUB_ID} is the original macro while ${PUBLISHERID} is the newer version.

DSP supports the following legacy macros:

Macro Syntax Description
Advertiser ID/Account ID {ADV_ID} Inserts the advertiser ID.
Cache Buster ${RANDOM_NUMBER} Inserts a timestamp or random number to ensure that a browser or proxy server requests a fresh creative on every ad call, rather than serving a previously served creative that remains in the browser’s cache. When you preview and test creatives, DSP replaces the macro with a random number or request ID to ensure that the creative displays properly.
Click Tracking {CLICK_URL_UNESC} Inserts a click-through URL so that clicking on the ad first directs users to the ad server (to record the click) before redirecting them to the advertiser’s URL specified in the HREF section of the tag. When the user clicks the ad, the macro sends the information to the redirect URL, enabling the platform to track and therefore count that click. Note: This macro can be used with both secure and non-secure creatives.
Click Tracking Double-Encoded {CLICK_URL_ESC_ESC} Inserts a double-encoded click tracking URL (see {CLICK_URL} above). Although rare, some vendors require double-encoded macros for click tracking. Note: This macro can be used with both secure and non-secure creatives.
Click Tracking Encoded {CLICK_URL_ESC} Inserts an encoded click URL for click tracking (see {CLICK_URL} above). Encoding is sometimes needed if the click tracking URL is used as a query parameter in another URL. Note: This macro can be used with both secure and non-secure creatives.
Creative ID {CREATIVE_ID} Inserts the creative ID.
Line ID {LINE_ID} Inserts the advertiser line item ID. This enables advertisers to track and gather information on the line, based on the ID.
Order ID / Campaign ID {ORDER_ID} Inserts the campaign ID (campaign = order).
Publisher ID / Exchange ID {PUB_ID} Inserts the exchange ID. Each exchange has a unique ID.
User ID {USERID_BASE64_ESC} Inserts the user ID for base encoding.

Third-Party Vendors

DSP displays a warning message if an unknown vendor is encountered when trying to add a third-party creative.

You can still force-save creatives for an unknown vendor, and your ads will build appropriately. However, if the vendor is unknown, you must provide at least one click-tracking macro and one cache busting macro, either manually or through appropriate use of pre-defined macros.

Macro Substitution

Macro substitution works as follows:

  • DSP attempts to substitute for the specified macros whenever it can. It will substitute cache busting macro, click tracking, or both.
  • Macro substitution will generate an error only if both click tracking and cache busting macros are not present (however, it does insert macros when possible).
  • In addition to looking for its own cache busting macros ( or $), the application also accounts for Javascript implementations of cache busting (e.g., use of math.random() or similar).

Smart Ads and Smart Macros

DSP supports smart ads with smart macros for display lines. If you want to use smart ads and smart macros, contact your DSP representative.