Documentation

Ad Tag Variables & Macros

Ad tag variables

Ad-servers may use ad tag variables to optimise fill rate and ad-targeting. Since version 4.5.10 Radiant Media Player supports several variables that can be added to your ad tag URL. Those ad tag variables will be replaced automatically by Radiant Media Player just before the ad tag URL is requested to the ad-server. This is supported for both Google IMA and rmp-vast.

Note that the below ad tag variables are only replaced when the player attempts to load the ad tag URL from the server - the player will not replace those variables within the body of the VAST or VMAP response for tracking URIs or redirects. See the VAST macros section for variables that can be replaced within the body of a VAST response.

The following ad tag variables are supported:

  • __domain__: the Internet domain where the player stands
  • __page-url__: the full page URL where the player stands
  • __referrer__: the page URL that brought the viewer to the page where the player stands
  • __player-width__: current player width in pixels
  • __player-height__: current player height in pixels
  • __random-number__: a 12-digits random number (generally used for cache busting)
  • __timestamp__: the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC (UNIX timestamp)
  • __mobile__: writes "mobile" if player is rendered on a mobile device
  • __ima__: writes "ima" if video ads are rendered with Google IMA
  • __item-title__: title for the currently playing video (taken from contentMetadata.title setting) - for playlist/related this variable is pulled from the JSON file for each item
  • __item-description__: description for the currently playing video (taken from contentMetadata.description setting) - for playlist/related this variable is pulled from the JSON file for each item
  • __item-duration__: duration in seconds for the currently playing video - only for on-demand streaming where mid/post rolls are used
  • __current-time__: current player time in seconds - only for on-demand streaming where mid/post rolls are used
  • __device-ua__: device user agent
  • __autoplay__: autoplay mode for player - value set is either auto or click
  • __muted__: muted mode for player - value set is either 1 (muted) or 0 (unmuted)
  • __language__: player language in ISO 639-1 (two-letter) format (value set by the viewer in browser or system settings) - examples: it, fr, en
  • __gdpr__: When added to an ad tag, this variable tells if GDPR is required 0 (no) or 1 (yes). This must be used with the __gdpr-consent__ macro. Example: https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml?gdpr=__gdpr__&gdpr_consent=__gdpr-consent__. The IAB Transparency and Consent Framework (TCF) v2.0 must be implemented on your site/app for this variable to work.
  • __gdpr-consent__: When GDPR is required, as defined by the __gdpr__ variable, this variable adds a GDPR consent string (a.k.a. TC string). If GDPR is not required, __gdpr-consent__ is replaced with ''. The IAB Transparency and Consent Framework (TCF) v2.0 must be implemented on your site/app for this variable to work.
  • __uspdata__: When added to an ad tag, this variable is replaced with the US Privacy String found on page (read from window.__uspapi API). Example: https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml?us_privacy=__uspdata__. The USP API must be implemented on your site/app for this variable to work.

All variables are replaced with string values - an empty string is used if they cannot be filled

The ad tag variables are automatically RFC3986 URI encoded when replaced as recommended in the VAST 3 specifications

Only the first instance of a given variable will be replaced - use JavaScript for multiple replacements or to append custom ad tag variables

Only use ad tag variables when your ad-server support them to avoid unnecessary computing at run time

Example:

https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml?height=__player-height__&width=__player-width__&url=__page-url__&title=__item-title__

When making the ad request the player will try to load:

https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml?height=360&width=640&url=https%3A%2F%2Fwww.radiantmediaplayer.com%2Fdocs%2Flatest%2Fad-tag-variables-macros.html&title=Ad%20Tag%20Variables%20And%20Macros

VAST macros

VAST macros as defined in the VAST 4.2 specification enable the video player to provide certain details to the ad server at the time tracking URIs are accessed or when the VAST tag is requested. Macros will automatically be replaced by the player when pinging tracking URIs.

Supported macros with Google IMA: up to VAST 4.1 macros as of November 2020

Supported macros with rmp-vast: up to VAST 4.2 macros as of November 2020

See the VAST 4.2 specifications for more information on VAST macros.

Google IMA SDK

When using the Google IMA SDK with Radiant Media Player (which is default), all ad tag variables supported by Google Ad Manager are supported. The IMA SDK will add targeting variables before sending the ad request to Google Ad Manager servers.

Example:

https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&url=%5Breferrer_url%5D&correlator=%5Btimestamp%5D&description_url=__page-url__
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.

©2015-2024 Radiant Media Player. All Rights Reserved.