Supported Macros for Passing Data to 3rd Parties

What are Macros?

In some cases, 3rd party ad providers (e.g. ad networks or ad servers) require that information about the video view or the user be passed to them as part of their ad tag, 3rd party tracking tags, or via an API.

The Video SSP Platform provides a number of macros that allow for passing information dynamically. Once implemented during trafficking setup, the macro will be populated with relevant information at run time.

 

How Macros Work?

Video SSP Supported Macros

For All Customers

{cachebreaker} or ${AdPlayer.cachebreaker} Generates a random number for cachebusting purposes in 3rd party ad tags and tracking tags.

Note: Specifically in the case of 1st party served companions that require a cachebuster, use {cachebreaker}.

 

For Marketplace Sellers and Platform Customers

Macro value Description
${appName} Mobile application name supplied by the application vendor or inventory seller.
${context.ip_address} The IP address of the end user. IP address can be used to identify a user's geo location.
${pub.external_id} or ${pid} The Video SSP ID assigned to the Video SSP account.
${pageDomain} The secondary domain of the site where the ad was served.
${context.session_id} or ${sessionId} The user's browser session ID for the video view.
${user_agent} The user agent for the video view. The user agent string identifies the user's browser and platform.
${companionId} The div id of the companion ad spot.
${id} The publisher defined ID for the video content.
${uid} The Video SSP generated unique user ID.
${width} The width of the video player frame (defined by the publisher).
${height} The height of the video player frame (defined by the publisher).
${duration} The duration of the video content (the ad will display before/during/after this content).
${videourl} The URL of the media file player asset.
${title} The title of the video content (defined by the publisher).
${description} The description of the video content (defined by the publisher).
${category} The list of categories assigned to the video content (defined by the publisher).
${DART.pub.category} The list of categories assigned to the video content (defined by the publisher), in DART-friendly format.
${keywords} The keywords of the video content (defined by the publisher).
${embeddingPageUrl} The URL of the embedding webpage for this view.
${a.platformOs} The device OS.  For example, Android, IPhone.
${a.platformDevice} The video platform.  For example, Online Video, Phone, Tablet, Internet TV, Game Console.
${gdpr} GDPR Jurisdiction - 0 = impression does not fall under GDPR jurisdiction, 1 = impression falls under GDPR jurisdiction.
${gdpr_consent} Consent string storing user’s individual consent preferences, generated by an IAB Transparency and Consent Framework-compliant Consent Manager Provider (CMP).

 

Custom Data Keys

The Video SSP Platform also supports variables ("macros") for your organization's custom keys that are passed in an ad request ${pub_context.MY_VARIABLE}, where you replace MY_VARIABLE with the custom key parameter.

Example:

Let's assume that you've set-up a custom data key in the {{name}} console with parameter name partnerId .

Your custom key macro used during trafficking setup should be ${pub_context.partnerId}.

To pass a complete string containing all customer data keys, use the following macro: ${context}

Result: The complete list of key-value pairs sent in the context field for this view.

 

For Marketplace(s) Buyers

For Ad for Marketplaces, only the following macros should be used:

Macro value Description
${appName} Mobile application name supplied by the application vendor or inventory seller.
${context.ip_address} The IP address of the end user. IP address can be used to identify a user's geo location.
${context.session_id} or ${sessionId} The user's browser session ID for the video view.
${user_agent} The user agent for the video view. The user agent string identifies the user's browser and platform.
${a.platformOs} The device OS.  For example, Android, IPhone.
${a.platformDevice} The video platform.  For example, Online Video, Phone, Tablet, Internet TV, Game Console.

 

Console buyers can use following macros for tracking events in their pixels (Campaigns > Digital Ad >Edit > Creatives tab >section Event Tracking):

Macro value Description
${deviceid} Advertising identifier for any device (iOS, Android, Windows, Roku, Xbox, etc)
${dvc_sid} Session id on devices



For Mobile Sellers

The following macros are available for mobile sellers who are specifically sending the respective data into the ad request.

Macro value Description
${appName} Mobile application name supplied by the application vendor or inventory seller.
${idfa} Apple identifier for advertising for IOS.
${aid} Advertising identifier for Android.
${deviceid} Advertising identifier for any device (iOS, Android, Windows, Roku, Xbox, etc).
${dvc_sid} Session id on devices. As some devices do not have a device id, a session id is the next substitute.
${nielsen_devid} Either iOS IDFA or Android AID depending upon what is provided by publisher.
${ip} The IP address of the original user, forwarded by the mobile publisher.
${user_agent} The user agent for the video view. The user agent string identifies the user's browser and platform.
${a.platformOs} The device OS.  For example, Android, IPhone.
${a.platformDevice} The video platform.  For example, Phone, Tablet, Internet TV.
${app_storeurl} Gives the app store url from the adtag parameters.
${app_storeurl_available} Tells whether the app store url is present in the adtag or not.
${app_bundle} Gives the app bundle from the adtag parameters if it is not there then it will get the app bundle from the app store url.
${location_available} Tells whether location of the user was available or not.
${lat} GPS latitude if provided by the publisher.
${lon} GPS longitude if provided by the publisher.


For additional details on the parameters, that may be passed in the query string of an ad request to use with macros see
Keys & Parameters for Targeting and Reporting Purposes.

 

Have more questions? Submit a request