Mobile App VAST Ad Tag Setup
Last updated on July 30, 2020
The following instructions are for publishers who do not use Fyber, ironSource, or MoPub and would like to configure a Video Ad Serving Template (VAST) ad tag for mobile app linear video ad units.
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 an example base tag, where the blurred section is a placeholder for your instance name. This base tag includes the ad unit ID (auid) and dr=true (no redirect for cookies) already appended.
When viewing your VAST ad tag, you will see a VAST URI.
Appending Parameters and Macros
After generating your base tag, you should append parameters and macros. Appending the required and highly recommended parameters adds an additional level of detail to your tag and ad request that can inform bids from buyers.
Appending macros enables you to pass information into those parameters dynamically, ensuring that the parameters you include are as accurate as possible. You can find the relevant macros in your ad server or video player’s documentation, depending on where you plan to traffic your VAST ad tag.
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.
Working with macros
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 mobile app-related ad requests. Note the following:
- Certain parameters are labeled Required because DSPs use those values to determine whether to bid on requests.
INSERT_MACROindicates that a macro is supported by your ad server, but OpenX does not have information about it. You can replaceINSERT_MACROstrings with actual macros, according to your ad server documentation.
To learn more about the macros that your ad server supports, see your ad server documentation.
| Parameter | Information that is passed | FreeWheel macro | LKQD macro | SpotX macro | SpringServe macro |
|---|---|---|---|---|---|
app.bundle | Required The app’s bundle ID. | {http:appBundle} | $$bundleid$$ | $BUNDLE | INSERT_MACRO |
app.name | Required The app’s display name. | {http:appName} | $$appname$$ | $APP_NAME | INSERT_MACRO |
cb | Required A random integer to avoid browser caching. | {cb} | $$cachebuster$$ | $CACHE_BUSTER | {{CACHEBUSTER}} |
crr | Mobile carrier, which is defined by the Mobile Country Code (MCC) and Mobile Network Code (MNC), using the format: <MCC>-<MNC>. | INSERT_MACRO | INSERT_MACRO | INSERT_MACRO | INSERT_MACRO |
gdpr | Whether the request is subject to the General Data Protection Regulation (GDPR). | INSERT_MACRO | $$gdpr$$ | $REGS_GDPR | {{GDPR}} |
gdpr_consent | A 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}} |
ifa | Required The Google Advertiser Device Identifier or Apple IDFA or from the user’s device. | {http:deviceIfa} | $$deviceid$$ | $DEVICE_IFA | {{UUID}} |
ip | The IP address from the user’s device. | {ip} | $$ip$$ | $IP_ADX | {{IP}} |
lat | The 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.530676 | INSERT_MACRO | $$loclat$$ | $GEO_LAT | {{LAT}} |
lmt | Required The setting from the user’s device that indicates if private browsing is enabled (if the user has requested not to be tracked). | INSERT_MACRO | INSERT_MACRO | $DEVICE_DNT | {{DNT}} |
lon | The 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.262447 | INSERT_MACRO | $$loclong$$ | $GEO_LON | {{LON}} |
net | The user’s network connection type. For a wireless network, use net=wifi. | INSERT_MACRO | INSERT_MACRO | INSERT_MACRO | INSERT_MACRO |
ua | Required The device user agent, which typically indicates the app or browser making the request. | {useragent} | $$useragent$$ | $USER_AGENT_ENCODED | INSERT_MACRO |
url | Required 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}} |
vht | Required The desired ad height. | height} | $$height$$ | $PLAYER_HEIGHT | {{HEIGHT}} |
vwd | Required The desired ad width. | width} | $$width$$ | $PLAYER_WIDTH | {{WIDTH}} |
Fully configured VAST ad tag with placeholders for macros
The example tag below shows a base VAST ad tag with the required and highly recommended parameters, as well as placeholders for macros. This is an opt-in video (rewarded video) tag, so it also includes the vrw parameter.
Specific integration types (like server-to-server) and inventory types have additional parameters. You can pass in parameters for settings you chose in the OpenX Ad Exchange user interface (UI) to dynamically override them as needed.
http://your-instance.openx.net/v/1.0/av?auid=0123456789&dr=true&url=INSERTMACRO&ifa=INSERTMACRO&lmt=INSERTMACRO&app.bundle=INSERTMACRO<=INSERTMACRO&lat=INSERTMACRO&lon=INSERTMACRO&af=INSERTMACRO&app.name=INSERTMACRO&vrw=INSERTMACRO&vht=INSERTMACRO&vwd=INSERTMACRO&&net=INSERTMACRO&crr=INSERTMACRO&cb=INSERTMACRO&ua=INSERTMACRO
Next Steps
- Copy your new tag from ad unit page and paste it into the appropriate location, according to your ad server documentation.
- Set up OpenX selling rules.