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__
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.
Updated about 1 year ago