Ad tag targeting macro reference


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

Targeting macros are used by both client-side and server-side ads servers. It is not uncommon to add 10+ macros to a single ad tag.

The following VAST tag example contains the __random-number__ macro.

https://example.adserver.com/vastResponse.xml?cb=__random-number__

In the previous example, __random-number__ is replaced with a random number (cachebuster). The ad server will receive an ad tag that looks similar to the following: https://example.adserver.com/vastResponse.xml?cb=98475983745983752

📘

If you are unsure how to fill out your ad tag macros, you will need to contact your ad network. They will inform you of any parameters you would add to boost your CPM. You can also find out if you need to add custom metadata to the video in a way that you can send to the player.



VAST

🚧

You may only use a specific ad tag macro type once in a single ad tag. As a workaround, try inserting the desired value via JavaScript concatenation in the ad tag URL string.


General

MACRODESCRIPTION
addtl_consent 8.24.1+When using a Consent Management Platform (CMP) that supports Google's Additional Consent Mode, adds a list of additional Google Ad Tech Providers

If the CMP does not support Additional Consent Mode, then addtl_consentis replaced with an empty string ("").

​Example: https://adtag.test.com/vast.xml?gdpr=__gdpr__&gdpr_consent=__gdpr_consent__&addtl_consent=__addtl_consent__

​The IAB Europe Transparency and Consent Framework must be implemented for this macro to work.
companion-divID of the companion div

This can be used to allow VPAID ads to talk to companions.
device-ua 8.11.0+User-Agent of the device rendering the ad to the end-user
gdpr 8.9.0+When added to an ad tag, adds an identifier that indicates if GDPR is required, 0 (no) or 1 (yes)

This must be used with the gdpr_consent macro.

Example: https://adtag.test.com/vast.xml?gdpr=__gdpr__&gdpr_consent=__gdpr_consent__

The IAB Europe Transparency and Consent Framework must be implemented for this macro to work.
gdpr_consent 8.9.0+When GDPR is required, as defined by the gdpr macro, adds a GDPR consent string

If GDPR is not required, gdpr_consent is replaced with "" (an empty string).

Example: https://adtag.test.com/vast.xml?gdpr=__gdpr__&gdpr_consent=__gdpr_consent__

The IAB Europe Transparency and Consent Framework must be implemented for this macro to work.
player-heightHeight of the video player on the page in pixels
player-widthWidth of the video player on the page in pixels
random-numberCache-buster to prevent caching of the VAST response
timestampCurrent time of the user's computer

OTT Apps

MACRODESCRIPTION
app-bundleBundle ID of the OTT App in the app store
app-namePublic name of the OTT App

Web

MACRODESCRIPTION
domainDomain name on which the player is embedded
page-urlURL of the current page in which the video is embedded
referrerURL of the page that brought the viewer to the current player

Content

MACRODESCRIPTION
item-{customparam}Custom parameters set on the currently playing video

If you want to include a custom parameter named contentid to your ad tag, you would replace {customparam} with contentid.

For example: __item-contentid__.
item-{customparam}-list 8.12.0+Custom parameters list set on the currently playing video

Unlike __item-{customparam}__ above, this variable ensures that commas are not URL-encoded in comma-delimited lists.

If you want to include a list of custom parameters named animal to your ad tag, you would replace {customparam} with animals.

For example: __item-animals-list__.
item-descriptionShort description of the currently playing video.1
item-durationDuration in seconds of the currently playing video

When using with a pre-roll, this only works when the duration is provided alongside the media URL in the player configuration or playlist feed.
item-fileFile URL of the currently playing video
item-mediaidCustom media ID of the currently playing video.1
item-titleTitle of the currently playing video.1
item-tagsMetadata tags set on the currently playing video

1. Must be specified inside of the playlist



Google IMA

For Google IMA, the following ad targeting macros are supported:

  • All ad targeting macros listed in the previous VAST section
  • All ad tag variables supported by Google Ad Manager (GAM)
  • Targeting variables added by the Google IMA SDK

As shown in the following example, users of GAM will however need to make minor alterations from the VAST examples above such as changing Google's description_url macro to description_url=page-url.

https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/88234159/video&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&description_url=__page-url__&correlator=__timestamp__

See the IMA SDK Documentation for more info.



FreeWheel

❗️

Ad tag targeting is not supported for FreeWheel.


For FreeWheel, proprietary targeting takes place as set up within FreeWheel's MRM platform.