Ad tag targeting macro reference

<img src="https://img.shields.io/badge/%20-ENTERPRISE-%23B10031" style="float:left"/><br />
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.
﻿
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.
<br />
﻿
## 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.
<br />
#### General
<table>
    <thead>
        <tr>
            <th> Macro </th>
            <th> Description </th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td width="34%"><strong>__addtl_consent__</strong> <sup>8.24.1+</sup></td>
            <td width="66%">When using a Consent Management Platform (CMP) that supports <a href="https://support.google.com/admanager/answer/9681920?hl=en" target="_blank">Google's Additional Consent Mode</a>, adds a list of additional Google Ad Tech Providers
                <br /><br />
                If the CMP does not support Additional Consent Mode, then <code>addtl_consent</code> is replaced with an empty string (<strong>""</strong>).
                <br /><br />
                <strong>Example</strong>: <code>https://adtag.test.com/vast.xml?gdpr=__gdpr__&gdpr_consent=__gdpr_consent__<br />&addtl_consent=__addtl_consent__</code>
                <br /><br />
                The <a href="https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework" target="_blank">IAB Europe Transparency and Consent Framework</a> <strong>must be</strong> implemented for this macro to work.
            </td>
        </tr>
        <tr>
            <td><strong>__companion-div__</strong></td>
            <td>ID of the companion div
                <br /><br />
                This can be used to allow VPAID ads to talk to companions.
            </td>
        </tr>
        <tr>
            <td><strong>__device-ua__</strong> <sup>8.11.0+</sup></td>
            <td>User-Agent of the device rendering the ad to the end-user</td>
        </tr>
        <tr>
            <td><strong>__gdpr__</strong> <sup>8.9.0+</sup></td>
            <td>When added to an ad tag, adds an identifier that indicates if GDPR is required, <code>0</code> (no) or <code>1</code> (yes)
                <br /><br />
                This must be used with the <code>gdpr_consent</code> macro.
                <br /><br />
                <strong>Example</strong>: <code>https://adtag.test.com/vast.xml?gdpr=__gdpr__&gdpr_consent=__gdpr_consent__</code>
                <br /><br />
                The <a href="https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework" target="_blank">IAB Europe Transparency and Consent Framework</a> <strong>must be</strong> implemented for this macro to work.
            </td>
        </tr>
        <tr>
            <td><strong>__gdpr_consent__</strong> <sup>8.9.0+</sup></td>
            <td>When GDPR is required, as defined by the <code>gdpr</code> macro, adds a GDPR consent string
                <br /><br />
                If GDPR is not required, <code>gdpr_consent</code> is replaced with <code>""</code> (an empty string).
                <br /><br />
                <strong>Example</strong>: <code>https://adtag.test.com/vast.xml?gdpr=__gdpr__&gdpr_consent=__gdpr_consent__</code>
                <br /><br />
                The <a href="https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework" target="_blank">IAB Europe Transparency and Consent Framework</a> <strong>must be</strong> implemented for this macro to work.
            </td>
        </tr>
        <tr>
            <td><strong>__player-height__</strong> </td>
            <td>Height of the video player on the page in pixels</td>
        </tr>
        <tr>
            <td><strong>__player-width__</strong> </td>
            <td>Width of the video player on the page in pixels</td>
        </tr>
        <tr>
            <td><strong>__random-number__</strong> </td>
            <td>Cachebuster to prevent caching of the VAST response</td>
        </tr>
        <tr>
            <td><strong>__timestamp__</strong> </td>
            <td>Current time of the user's computer</td>
        </tr>
    </tbody>
</table>
<br />
#### Apps
<table>
    <thead>
        <tr>
            <th>Macro</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td width="34%"><strong>__app-bundle__</strong> </td>
            <td width="66%">Bundle ID of the OTT App in the app store</td> </tr>
        <tr>
            <td><strong>__app-name__</strong></td>
            <td>Public name of the OTT App</td>
        </tr>
    </tbody>
</table>
<br />
#### Web
<table>
    <thead>
        <tr>
            <th>Macro</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td width="34%"><strong>__domain__</strong></td>
            <td width="66%">Domain name on which the player is embedded</td>
        </tr>
        <tr>
            <td><strong>__page-url__</strong></td>
            <td>URL of the current page in which the video is embedded</td>
        </tr>
        <tr>
            <td><strong>__referrer__</strong></td>
            <td>URL of the page that brought the viewer to the current player</td>
        </tr>
    </tbody>
</table>
<br />
#### Content
<table>
    <thead>
        <tr>
            <th> Macro </th>
            <th> Description </th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td width="34%"><strong>__item-{customparam}__</strong> </td>
            <td width="66%">Custom parameters set on the currently playing video
                <br /><br />
                If you want to include a custom parameter named  <code>contentid</code>  to your ad tag, you would replace  <code>{customparam}</code>  with  <code>contentid</code>.  
                <br /><br />
                <strong>Example</strong>: <code>__item-contentid__</code>
            </td>
        </tr>
        <tr>
            <td><strong>__item-{customparam}-list__</strong></td>
            <td>Custom parameters list set on the currently playing video
                <br /><br />
                Unlike  <code>__item-{customparam}__</code> above, this variable ensures that commas are not URL-encoded in comma-delimited lists.
                <br /><br />
                If you want to include a list of custom parameters named animal to your ad tag, you would replace <code>{customparam}</code> with <code>animals</code>.
                <br /><br />
                <strong>Example</strong>: <code>__item-animals-list__</code>  
            </td>
        </tr>
        <tr>
            <td><strong>__item-description__</strong> </td>
            <td>Short description of the currently playing video <sup><a href="#1">1</a></sup></td>
        </tr>
        <tr>
            <td><strong>__item-duration__</strong> </td>
            <td>Duration in seconds of the currently playing video
                <br /><br />
                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.
            </td>
        </tr>
        <tr>
            <td><strong>__item-file__</strong> </td>
            <td>File URL of the currently playing video</td>
        </tr>
        <tr>
            <td><strong>__item-mediaid__</strong> </td>
            <td>Custom media ID of the currently playing video <sup><a href="#1">1</a></sup></td>
        </tr>
        <tr>
            <td><strong>__item-title__</strong> </td>
            <td>Title of the currently playing video <sup><a href="#1">1</a></sup></td>
        </tr>
        <tr>
            <td><strong>__item-tags__</strong> </td>
            <td>Metadata tags set on the currently playing video</td>
        </tr>
    </tbody>
</table>
<a name="1"></a>1. Must be specified inside of the playlist​
<br /><br />
### 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**.
﻿
See the  [IMA SDK Documentation](🔗﻿)  for more info.
​<br /><br />
### FreeWheel
﻿
Ad tag targeting is not supported for FreeWheel.
For FreeWheel, proprietary targeting takes place as set up within FreeWheel's MRM platform.
<br />
﻿
## Server-Side Ad Insertion
<a name="vast-ssai"></a>
### VAST
<br />
<a name="vast-general-ssai"></a>
#### General
<table>
    <thead>
        <tr>
            <th> Macro </th>
            <th> Description </th>
            <th> Preroll</th>
            <th> Midroll</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td width="34%"><strong>__device-ua__</strong> </td>
            <td width="46%">User-Agent of the device rendering the ad to the end-user</td>
            <td with="10%"><div style="text-align:center">✅</div></td>
            <td with="10%"><div style="text-align:center">✅</div></td>
        </tr>
        <tr>
            <td><strong>__random-number__</strong> </td>
            <td>Cachebuster to prevent caching of the VAST response</td>
            <td><div style="text-align:center">✅</div></td>
            <td><div style="text-align:center">✅</div></td>
        </tr>
        <tr>
            <td><strong>__referrer__</strong> </td>
            <td>Player referrer header</td>
            <td><div style="text-align:center">✅</div></td>
            <td><div style="text-align:center">✅</div></td>
        </tr>
        <tr>
            <td><strong>__scte-event_id__</strong> </td>
            <td>SCTE35 event ID, if present</td>
            <td><div style="text-align:center">🚫</div></td>
            <td><div style="text-align:center">✅</div></td>
        </tr>
        <tr>
            <td><strong>__scte-segmentation_upid__</strong> </td>
            <td>SCTE35 segmentation unique program ID, if present</td>
            <td><div style="text-align:center">🚫</div></td>
            <td><div style="text-align:center">✅</div></td>
        </tr>
        <tr>
            <td><strong>__session-avail_duration_secs__</strong> </td>
            <td>Ad break duration in seconds</td>
            <td><div style="text-align:center">🚫</div></td>
            <td><div style="text-align:center">✅</div></td>
        </tr>
        <tr>
            <td><strong>__session-client_ip__</strong> </td>
            <td>Client IP address</td>
            <td><div style="text-align:center">✅</div></td>
            <td><div style="text-align:center">✅</div></td>
        </tr>
        <tr>
            <td><strong>__session-uuid__</strong> </td>
            <td>Unique session UUID</td>
            <td><div style="text-align:center">✅</div></td>
            <td><div style="text-align:center">✅</div></td>
        </tr>
    </tbody>
</table>
<br />
<a name="vast-content-ssai"></a>
#### Content
<table>
    <thead>
        <tr>
            <th> Macro </th>
            <th> Description </th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td width="34%"><strong>__item-{customparam}__</strong> </td>
            <td width="66%">Either media custom parameters or query string parameters passed directly from the player
                <br /><br />
                Broadcast Live custom parameters have categories. If you want to include a custom parameter named <code>contentid</code> in category called <code>contentgroup</code> to your ad tag, you would replace  <code>{customparam}</code>  with <code>contentgroup.contentid</code>.  
                <br /><br />
                <strong>Example</strong>: <code>__item-contentgroup.contentid__</code>
            </td>
        </tr>
    </tbody>
</table>
​<br /><br />
<a name="freewheel-ssai"></a>
### FreeWheel
﻿
Ad tag targeting is not supported for FreeWheel.
For FreeWheel, proprietary targeting takes place as set up within FreeWheel's MRM platform.
<br />
<!-- Removes the automatic page-to-page navigation at the bottom of the page -->
<style>
.rm-Pagination {
  display: none;
}
</style>