Ad tag targeting macro reference

Ad tag targeting macros are placeholders that pass contextual information with an ad request. When JWX processes a supported macro, it replaces the placeholder with a value from the request context, such as the page, player, device, content, or ad break.

Macros can help ad servers improve targeting, reporting, and fill. The available macros and supported syntax depend on where the ad tag is configured, the ad integration, and whether ads are inserted client-side or server-side.

Supported formats and usage

Supported formats

JWX supports two macro formats:

JWX format: __macro-name__
CNX format: [MACRO_NAME]

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

https://example.adserver.com/vastResponse.xml?cb=[CB]

In both examples, the ad server receives a request URL similar to the following: https://example.adserver.com/vastResponse.xml?cb=98475983745983752

Usage

The following table identifies the macro formats supported by each ad tag workflow.

Ad insertion method	Ad tag configuration	JWX format	CNX format
Client-side	Creative URL in the JWX Ad Server	🚫	✅
Client-side	Ad tag provided through Dynamic Strategy Rules	✅	✅
Client-side	Client-side ad tag provided directly to a JWX player or SDK	✅	✅
Server-side	JWX server-side ad insertion configuration	✅	🚫

📘
Contact your ad network if you are unsure which macros or parameters to include in your ad tag. Your ad network can identify the values needed for targeting and monetization and advise whether you must add custom metadata to your video configuration.

Client-Side Ad Insertion

🚧
JWX and CNX macro names are not interchangeable.
Use only the exact macro names listed in this reference. The availability of a CNX macro does not imply that an equivalent JWX macro is available. For example, [AD_POSITION] is a supported CNX macro, but __AD_POSITION__ is not a supported JWX macro.

VAST

Ad placement and playback

JWX macro	CNX macro	Description
random-number	[CB]	Cachebuster to prevent reusing an ad that has already been seen and cached
timestamp	---	Unix timestamp representing when the ad request is made
---	[AD_POSITION]	Position of the ad break relative to the video content Possible values: (Default) `midRoll` `postRoll` `preRoll`
---	[AUTOPLAY]	Indicates if video playback starts automatically without user action
---	[MUTE]	Indicates whether the video player is muted when the ad request is made Possible values: `0`: Sound on `1`: Muted
---	[PLCMT]	Video placement type indicating the context in which the player and ad appear
---	[VIDEO_TIME]	Current playback position, in seconds, within the video

Auction and supply chain

JWX macro	CNX macro	Description
---	[SCHAIN]	OpenRTB SupplyChain object associated with the ad request NOTE: This value is passed to Prebid.js as a structured OpenRTB SupplyChain object. It is not replaced directly in the ad tag URL.

JWX macro

CNX macro

Description

---

[SCHAIN]

OpenRTB SupplyChain object associated with the ad request

NOTE: This value is passed to Prebid.js as a structured OpenRTB SupplyChain object. It is not replaced directly in the ad tag URL.

Privacy and identity

JWX macro	CNX 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.
__gdpr__ ^8.9.0+	[GDPR]	When added to an ad tag, adds an identifier that indicates if GDPR is required, `0` (no) or `1` (yes) Use `__gdpr__` with `__gdpr_consent__`, or `[GDPR]` with `[GDPR_CONSENT]`. 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+	[GDPR_CONSENT]	When GDPR applies, inserts the full, Base64-encoded Transparency and Consent (TC) string provided by the site's consent management platform (CMP) This string contains the user's consent choices rather than a binary indication of consent for a specific advertising vendor. 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 (TCF) must be implemented for this macro to work.
---	[CONSENT]	Indicates whether the user has granted consent to the advertising vendor associated with the current ad line item: `1`: GDPR does not apply, or GDPR applies and the user has granted consent to the vendor. `0`: GDPR applies and the user has not granted consent to the vendor.
---	[DNT]	Do Not Track preference reported by the user’s browser
---	[US_PRIVACY]	IAB U.S. Privacy String representing the user’s California Consumer Privacy Act (CCPA) privacy choices
---	[UUID]	Unique identifier used to track the user NOTE: This macro is populated only when both Connatix consent and consent for the applicable vendor have been granted. Otherwise, the macro resolves to an empty value.

Device and location

JWX macro	CNX macro	Description
device-ua^8.11.0+	[UA]	User-Agent of the device rendering the ad to the end-user
---	[IP]	IP address of the end user
---	[USER_LAT]	Latitude of the end user’s location
---	[USER_LONG]	Longitude of the end user’s location

Page and player

JWX macro	CNX macro	Description
companion-div	---	ID of the companion `<div>` This can be used to allow VPAID ads to talk to companions.
domain	[DOMAIN] [SITE]	Domain name of the page where the player is embedded Example: `www.mydomain.com`
page-url	[PAGE_URL]	Domain, path, and query string of the page containing the player, excluding the protocol Example: `www.mydomain.com/6151792/all-movies-ranked/`
player-height	[HEIGHT]	Height of the video player on the page in pixels
player-width	[WIDTH]	Width of the video player on the page in pixels
referrer	[SOURCE_REFERRER]	URL of the page that referred the viewer to the page containing the player NOTE: When using `__referrer__`, JWX URL-encodes the referrer value before replacing the macro.
---	[DESCRIPTION_URL]	URL of the page containing the player, provided to the ad server for contextual targeting
---	[PUBLISHER]	URL of the publisher page containing the player
---	[URL]	Full URL of the page containing the player, including the protocol Example: `https://www.mydomain.com/6151792/all-movies-ranked/`

Apps

JWX macro	CNX macro	Description
app-bundle	[APP_BUNDLE]	Bundle ID of the OTT App in the app store
app-name	[APP_NAME]	Public name of the OTT App
---	[APP_URL]	App store URL for the application containing the player

Content

JWX macro	CNX macro	Description
__item-{customparam}__	---	Custom parameters set on the currently playing video
__item-{customparam}-list__	---	Custom parameters list set on the currently playing video
__item-description__	[VIDEO_DESCRIPTION]	Short description of the currently playing video NOTE: When using `__item-description__`, the media description must be specified in the playlist.
__item-duration__	[CONTENT_LENGTH] [VIDEO_DURATION]	Duration in seconds of the currently playing video NOTE: When used with a pre-roll, the media URL must include an associated duration in the player configuration or playlist feed.
__item-file__	---	File URL of the currently playing video
__item-mediaid__	[VIDEO_ID]	Media ID of the currently playing video NOTE: When using `__item-mediaid__`, the media ID must be specified in the playlist.
__item-tags__	---	Metadata tags set on the currently playing video
__item-title__	[MEDIA_TITLE] [VIDEO_TITLE]	Title of the currently playing video NOTE: When using `__item-title__`, the video title must be specified in the playlist.
---	[VIDEO_KEYWORDS]	Comma-separated words derived from the video
---	[VIDEO_URL]	URL associated with the video content NOTE: Depending on the integration, this may be the video click-through URL or media source URL.

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.