Ad tag targeting macro reference

Many VAST servers use tag variables to optimize fill and provide more information on how ads are being viewed. JWX supports a number of variables that can be added to your VAST tag URL. Once an ad call is made by JWX, 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.

Client-Side Ad Insertion

VAST

General

Macro	Description
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_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.
companion-div	ID 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-height	Height of the video player on the page in pixels
player-width	Width of the video player on the page in pixels
random-number	Cachebuster to prevent caching of the VAST response
timestamp	Current time of the user's computer

Apps

Macro	Description
app-bundle	Bundle ID of the OTT App in the app store
app-name	Public name of the OTT App

Web

Macro	Description
domain	Domain name on which the player is embedded
page-url	URL of the current page in which the video is embedded
referrer	URL of the page that brought the viewer to the current player

Content

Macro	Description
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`. Example: `item-contentid`
item-{customparam}-list	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`. Example: `item-animals-list`
item-description	Short description of the currently playing video ¹
item-duration	Duration 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-file	File URL of the currently playing video
item-mediaid	Custom media ID of the currently playing video ¹
item-title	Title of the currently playing video ¹
item-tags	Metadata 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.

Server-Side Ad Insertion

VAST

General

Macro	Description	Preroll	Midroll
device-ua	User-Agent of the device rendering the ad to the end-user	✅	✅
random-number	Cachebuster to prevent caching of the VAST response	✅	✅
referrer	Player referrer header	✅	✅
scte-event_id	SCTE35 event ID, if present	🚫	✅
scte-segmentation_upid	SCTE35 segmentation unique program ID, if present	🚫	✅
session-avail_duration_secs	Ad break duration in seconds	🚫	✅
session-client_ip	Client IP address	✅	✅
session-uuid	Unique session UUID	✅	✅

Content

Macro Description

Macro	Description
item-{customparam}	Either media custom parameters or query string parameters passed directly from the player Broadcast Live custom parameters have categories. If you want to include a custom parameter named `contentid` in category called `contentgroup` to your ad tag, you would replace `{customparam}` with `contentgroup.contentid`. Example: `item-contentgroup.contentid`

item-{customparam}

Either media custom parameters or query string parameters passed directly from the player

Broadcast Live custom parameters have categories. If you want to include a custom parameter named contentid in category called contentgroup to your ad tag, you would replace {customparam} with contentgroup.contentid.

Example: item-contentgroup.contentid

FreeWheel

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

📘
Contact your FreeWheel representative for more information.