Ad Tag Targeting Macros

To access these features, Upgrade Now

Many VAST servers use "tag variables" to optimize fill and provide more information on how ads are being viewed. JW Player supports a number of variables that can be added to your VAST tag URL. Once an ad call is made by JW Player, the variables will be replaced accordingly.

Supported Ad Tag Variables in VAST

The ID of the companion div, for example to allow VPAID ads to talk to companions.
The domain name the player is embedded on.
The height of the video player on the page in pixels.
The width of the video player on the page in pixels.
Typically used as a cache-buster, to ensure there is no local caching of the VAST response.
The URL of the current page (the one the video is embedded in).
The current time of the user's computer, as a UNIX timestamp.
The URL of the page that brought the viewer to the current player.

Playlist Item Properties

Playlist item properties allow publishers to send any metadata from the JW Player Playlist to an ad server. Assuming that you had something entered in your playlist XML like:


You would then be able to use the __item-artist__ variable in your ad tag. When making a call to an ad server, we will automatically fill this in as Leonardo. This is helpful to target ads to metadata keywords or to target different ads to each item in a playlist. Here are a few more example properties:

  • __item-title__: the title of the currently playing video.1
  • __item-description__: the short description of the currently playing video.1
  • __item-mediaid__: the custom media id of the currently playing video.1
  • __item-file__: the file URL of the currently playing video.
  • __item-duration__: the duration in seconds of the currently playing video. (Only works with midroll and postroll ads)
  • __item-tags__: the metadata tags set on the currently playing video
  • __item-customparam__: the metadata custom parameters set on the currently playing video
1Must be specified inside of the playlist.


Here is an example VAST tag with the __random-number__ variable being used. Please note that this is how a tag should appear when setting it within the player embed:


Once the ad tag is called from the JW Player, we will see which variables are being used, and populate these variables appropriately. In this instance, the above tag will make a call to the ad server as:

Please note: 
  • Ad tag variables are replaced with an empty string if they cannot be filled.
  • You may only use each ad tag macro type once in an single ad tag. As a workaround, please try inserting the desired value via Javascript concatenation in the ad tag URL string. For example, to include a second macro for the value '__page-url__': //"+encodeURIComponent(location.href)}

See Basic Preroll Ads to learn how to setup ad tags in JW Player.

Google IMA

For IMA, all tag variables supported by DFP are supported. The IMA SDK automatically adds serveral targeting variables prior to sending the request to DFP.

Users of DFP will however need to make minor alterations from the VAST examples above such as changing the description_url macro to &description_url=page-url&, per this example:

See the IMA SDK Documentation for more info.


For FreeWheel, proprietary targeting takes place as set up within FreeWheel's MRM platform. Ad tag targeting is not supported for FreeWheel.

Did you find this article helpful?

Please log in to rate this article.