Link Search Menu Expand Document

PDF

Web VAST Ad Tag Setup

Publishers

Last updated on July 18, 2019


The following instructions are for publishers who would like to configure a VAST ad tag for either desktop web or mobile web.

In order to complete the setup of a video ad unit and start serving video ads, you must configure the base VAST ad tag generated when you created a linear video ad unit.

The screenshot below shows the base tag that results from creating a linear video ad unit, where the blurred section is a placeholder for your instance name.


Simple Web Video Integration

If you only need a simple integration (without dynamic parameters, run-of-network, or run-of-site) you need only append the URL of the page with your video player. The use case for this simple setup is a website with a video player on a single page. In other setup use cases, you will need to append macros as instructed below.

Below is an example of a simple VAST ad tag with a placeholder URL for the video player’s static page:

http://your-instance.openx.net/v/1.0/av?auid=1234567890&url=http://www.your-site.com/home
  • Base tag: http://your-instance.openx.net/v/1.0/av?auid=1234567890
  • URL parameter: &url=
  • A placeholder page URL with full HTTP path: http://www.your-site.com/home.html

Appending Parameters and Macros

After receiving the base tag with ad unit ID, you should append parameters and macros. Appending the required and highly recommended parameters adds an additional level of detail to your tag.

Macros are fields or placeholders for information that you specify about your inventory and the types of creative you want to appear in it. Your ad sever populates these fields with specific values. When your ad server sends an ad request to OpenX Ad Exchange, these macro values are translated into parameters that help demand partners make bidding decisions about your inventory.

When you generate a VAST tag, based on the attributes of an ad unit, the tag includes some dynamically appended macros, as you can see in the preceding screen shot examples. You can insert additional macros in ad tags to automatically capture other user-specific parameters. However, if you want to define additional inventory-specific parameters, you must do so manually with URL-encoded values.

The following table maps your ad server’s macros to OpenX parameters for CTV-related ad requests. Note the following:

  • Certain parameters are labeled Required because DSPs use those values to determine whether to bid on requests.
  • INSERT_MACRO indicates that a macro is supported by your ad server, but OpenX does not have information about it. You can replace INSERT_MACRO strings with actual macros, according to your ad server documentation.

To learn more about these parameters, see Ad request parameters.

To learn more about the macros that your ad server supports, see your ad server documentation.

ParameterInformation that is passedFreeWheel macroLKQD macroSpotX macroSpringServe macro
app.bundleRequired
The app’s bundle ID.
{http:appBundle}$$bundleid$$$BUNDLEINSERT_MACRO
app.nameRequired
The app’s display name.
{http:appName}$$appname$$$APP_NAMEINSERT_MACRO
cbRequired
A random integer to avoid browser caching.
{cb}$$cachebuster$$$CACHE_BUSTER{{CACHEBUSTER}}
crrMobile carrier, which is defined by the Mobile Country Code (MCC) and Mobile Network Code (MNC), using the format: <MCC>-<MNC>.INSERT_MACROINSERT_MACROINSERT_MACROINSERT_MACRO
gdprWhether the request is subject to the General Data Protection Regulation (GDPR).INSERT_MACRO$$gdpr$$$REGS_GDPR{{GDPR}}
gdpr_consentA declaration that that the user has consented to having his or her data collected by the publisher’s site, as mandated by the GDPR.INSERT_MACRO$$gdprcs$$$USER_CONSENT{{CONSENT}}
ifaRequired
The Google Advertiser Device Identifier or Apple IDFA or from the user’s device.
{http:deviceIfa}$$deviceid$$$DEVICE_IFA{{UUID}}
ipThe IP address from the user’s device.{ip}$$ip$$$IP_ADX{{IP}}
latThe GPS latitude location, in decimal form, of the device. You should send the lt parameter with lat/lon. This is passed to buyers as OpenRTB device.geo data (not user.geo). For example: lat=37.530676INSERT_MACRO$$loclat$$$GEO_LAT{{LAT}}
lmtRequired
The setting from the user’s device that indicates if private browsing is enabled (if the user has requested not to be tracked).
INSERT_MACROINSERT_MACRO$DEVICE_DNT{{DNT}}
lonThe GPS longitude location, in decimal form, of the device. You should send the lt parameter with lat/lon. This is passed to buyers as OpenRTB device.geo data (not user.geo). For example: lon=-122.262447INSERT_MACRO$$loclong$$$GEO_LON{{LON}}
netThe user’s network connection type. For a wireless network, use net=wifi.INSERT_MACROINSERT_MACROINSERT_MACROINSERT_MACRO
uaRequired
The device user agent, which typically indicates the app or browser making the request.
{useragent}$$useragent$$$USER_AGENT_ENCODEDINSERT_MACRO
urlRequired
The mobile app store URL or the mobile website URL. The URL for mobile apps can be HTTP or HTTPS. Non-app store mobile websites should use HTTPS URLs for secure sites.
   • For iOS, it is the App Store URL. For example: url=https://itunes.apple.com/us/app/talking-tom-cat/id377194688?mt=8
   • For Android, it is the Google Play URL. For example: url=https://play.google.com/store/apps/details?id=com.outfit7.talkingtom&hl=en
{http:appStoreUrl}$$appstoreurl$$$APP_STOREURL{{URL}}
vhtRequired
The desired ad height.
height}$$height$$$PLAYER_HEIGHT{{HEIGHT}}
vwdRequired
The desired ad width.
width}$$width$$$PLAYER_WIDTH{{WIDTH}}

Fully configured VAST ad tag with placeholders for macros

In the example below, you could pass in the parameters for URL, video player height, and video player width to dynamically override the values you entered in the OpenX UI as needed.

The VAST ad tag sample below is described as follows:

http://your-instance.openx.net/v/1.0/av?auid=123456789&url=INSERT MACRO&vht=INSERT MACRO&vwd=INSERT MACRO
  • Base tag: http://your-instance.openx.net/v/1.0/av?auid=123456789
  • Parameters which must be configured exactly to our specifications: &url=, &vht=, and &vwd.
  • A placeholder for the relevant macro: INSERT MACRO

Next Steps

  1. Copy your new tag from ad unit page and paste it into the appropriate location, according to your ad server documentation.
  2. Set up OpenX selling rules.

If you need to express your traffic in real time in a detailed way, you can augment your ad tag with our OpenRTB object query string argument. For more information, see OpenRTB supply-side ad request parameter values.