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.



Client-Side Ad Insertion

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

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__
&addtl_consent=__addtl_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 1
__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 1
__item-title__ Title of the currently playing video 1
__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
__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

❗️

Ad tag targeting is not supported for FreeWheel.

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