Vungle VAST Integration Guide

This article describes the Vungle process and specifications for DSP partners serving VAST ads on the Vungle Exchange. For more information, refer to the IAB VAST 2.0 document.

Support

  • Vungle Exchange supports VAST 2.0 and 3.0.
    • Vungle Exchange does NOT support VPAID
    • Vungle Exchange does NOT support MRAID video. Refer to our MRAID documentation for more information.
  • Vungle Exchange supports VAST on Interstitial, Rewarded, and MREC ad formats
  • VAST InLine and Wrapper
  • XML must contain:
    • one .mp4 or .m3u8 media file
    • bitrate information
    • mediafile length information
    • mediafile height and width
    • secure assets
  • Must click through to landing page
    • Any redirects can only redirect a maximum of one time
    • Must support SSL
  • Supported media MIME types:
    • Android: video/mp4, application/x-mpegURL
    • iOS: video/mp4, application/x-mpegURL
  • Unsupported media MIME types:
    • MOV, Flash, HLS
  • File size limits:
    • Maximum 120-second video duration
    • Minimum bitrate of 250 kbps
  • Response time:
    • for streaming: must be within 250ms
    • for pre-cached: must be within 750ms
  • VAST extensions are optional, but preferred

Vungle will return an error if any of the above requirements are not met.

Endcards (CompanionAds)

We encourage all DSP partners to run endcards to increase performance. VAST-capable inventory supports companion ads, or endcards.

Implementation

In the VAST response, inside the <CompanionAds> element and define at least one <Companion> node with the desired resource file information for the endcard. The resource file can be of type <StaticResource> or <HTMLResource>.

StaticResource

The following is an example of a static image endcard.

Sample Code

<CompanionAds>
    <Companion>
        <StaticResource creativeType="image/jpeg">
            < [CDATA[https://Your_endcard_image_url]]>  // Required
        </StaticResource>
        <TrackingEvents>
            <Tracking event='creativeView'>
                < [CDATA[https://endcard_tracking]]>  // Required
            </Tracking>
        </TrackingEvents>
        <CompanionClickThrough>
            < ![CDATA[https://endcard_click_through]]>  // Required
        </CompanionClickThrough>
        <CompanionClickTracking>
            < ![CDATA[https://endcard_click_tracking]]> // Required
        </CompanionClickTracking>
    </Companion>
</CompanionAds>

HTMLResource

The following is an example of an HTML endcard.

Sample Code

<CompanionAds>
    <Companion>
        <HTMLResource>
            <![CDATA[
    <div>Your end card content</div> // Content can not be empty
    <script src=""></script>
    ]]>
        </HTMLResource>
        <TrackingEvents>
            <Tracking event='creativeView'>
                < ![CDATA[https://endcard_tracking]]> // Required
            </Tracking>
        </TrackingEvents>
    </Companion>
</CompanionAds>

Streaming

HLS streaming is supported on iOS versions >= 11 for fullscreen inventory only. HLS is not supported for mrec video. Vungle Exchange will pass the value '1' in the BidRequest.imp.video.delivery field of the bid request to indicate that a bid request is eligible for streaming. Please do not respond to bid requests with streaming video unless they support streaming.

If bidding on steaming eligible inventory with streaming video, make sure to include the following in the bid response:

  • MIME type (type) must be must be application/x-mpegURL
  • Delivery should be passed as streaming
  • Media file URI extension must be .m3u8
  • If you provide multiple .mp4/.m3u8 media files in the VAST, we will pick the first valid media file

Open Measurement

Refer to our Viewability Tracking article for VAST video requirements.

VAST Request Parameters

Parameter Name Macro Value Notes Example
App Category {{{pub_app_store_category}}} String List of categories Games
App Name {{{pub_app_name}}} String From the iTunes or Play store Family Farm Seaside
App Store URL {{{pub_app_store_url}}} String App Store or content URL. Encoded. https://play.google.com/store/apps/details?id=com.funplus.familyfarm&hl=en
Bundle ID {{{pub_market_app_id}}} String/Int From the iTunes or Play store com.funplus.familyfarm&hl=en (Android)
539920547 (iOS)
City {{{city}}} String Encoded New York
Connection Type {{{connection_type}}} String Wifi, wwan, mobile Wifi, wwan, mobile
Country {{{country}}} String Two-letter country code US
Device DNT {{{ad_tracking_disabled}}} String 'True' indicates that user does not allow ad tracking True/False
Device DNT {{{ad_tracking_enabled}}} String 'True' indicates that user does allow ad tracking True/False
Device DNT {{{boolean_number ad_tracking_disabled}}} Int Do not track, in binary form 0 – False
1 - True 
Device ID {{{device_id}}} String Clear or Hashed ab4d6cc4-f57f-4309-9d29-b7fb5e35dd74
Device Model {{{device_model}}} String Encoded Amazon,KFFOWI
samsung,SM-J700T
IP {{{ip}}} String Internet Protocol Address 95.118.153.77
Language {{{language}}} String Two-character Language from headers  10.2.1
OS version {{{os_version}}} String OS Version (ie iOS 7.2) 2014-12-05T00%3A44%3A19%2B00%3A00
Platform {{{device_platform}}} String iOS or Android iOS/Android
Screen Height {{{screen_height}}} Integer Screen height (pixels) 768
Screen Orientation {{{screen_orientation}}} String Portrait or Landscape Portrait/Landscape
Screen Width {{{screen_width}}} Integer Screen width (pixels) 1024
Timestamp {{{timestamp}}} String/Int Encoded 2014-12-05T00:44:19+00:00
User Agent {{{browser_user_agent}}} String UA from headers. Encoded. Mozilla/5.0 (Linux; Android 5.1.1; VF-1397 Build/LMY47V; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/55.0.2883.91 Safari/537.36
Vungle ID {{{vungle_id}}} String Vungle Publisher ID to associate performance 5497c989a3b61ba3660001b1

Sample VAST Request URLs

Sample VAST request URL (VAST tag) with unfilled parameters

https://partner.com/vast2/6524rgww153hifw/?duration=15&app_name={{{pub_app_name}}}&app_id={{{market_id}}}&rtb_type=instream_mobile_vast_inter&user_id={{{device_id}}}&ua={{{browser_user_agent}}}&random={{{timestamp}}}&ip_address={{{ip}}} 

Sample VAST request URL (VAST tag) with filled parameters

https://partner.com/vast2/124765432/?duration=15&app_name=My%20Talking%20Tom%20Free%20for%20Android&app_id=com.outfit7.mytalkingtomfree&rtb_type=instream_mobile_vast_inter&user_id=6df43c89-9e3d-43fb-a1e9-bacd51932d41&ua=Mozilla%2F5.0%20(Linux%3B%20Android%204.4.2%3B%20SPH-L720%20Build%2FKOT49H)%20AppleWebKit%2F537.36%20(KHTML%2C%20like%20Gecko)%20Version%2F4.0%20Chrome%2F30.0.0.0%20Mobile%20Safari%2F537.36&random=2015-01-27T21%3A30%3A34%2B00%3A00&ip_address=66.87.114.254 

VAST Error Code

Vungle Exchange supports VAST error codes on VAST 2.0 and 3.0. Additionally, Vungle Exchange displays VX Error Message on the Vungle Exchange DSP Demo App to give DSP more details for creative troubleshooting.

The following example is a sample VAST response that includes the <Error> element for an inline ad.

<InLine>
       …
       <Error> 
<![CDATA[https://adserver.com/error.gif/?error_code=[ERRORCODE]]>
       </Error>
       …
</InLine>

Notes:

  • The error tracking URL must use 'https'. 'http' is not accepted.
  • If the error_code parameter is provided, the macro [ERRORCODE] is case-sensitive.
  • If a VAST file triggers multiple errors, we report the first error with the IAB Error Code, and we list all the errors with the VX Error Message on the Vungle Exchange DSP Demo App.

The following error codes are supported by Vungle Exchange:

Error Code IAB Description VX Error Message
100 XML parsing error. Append dynamic error message
101 VAST schema validation error. Vast misses Ad
Ad should only contain one of Inline and Wrapper
Inline misses AdTitle
Inline AD misses Creatives
Inline misses Impressions
MediaFiles are missed
Creative should contain one type of NonLinearAds, Linear, CompanionAds
Wrapper misses VastAdTagURI
Wrapper misses Impressions
102 VAST version of response not supported. Version is not supported
300 General Wrapper error. Duration is negative
Duration is zero
Video duration is too long
Video duration is too short
303 No Ads VAST response after one or more Wrappers. No vast entity in adm
400 General Linear error. Video player is unable to display the Linear Ad. The MIMEType in the MediaFile is not supported
ErrMediaFile miss Delivery
Delivery does not equal `progressive` and `streaming`
The width and height of MediaFile should be greater than zero
ErrMediaFile miss URI
The width of the MediaFile is too high
The width of the MediaFile is too low
The heigth of the MediaFile is too high
The heigth of the MediaFile is too low
Min bit rate of Mediafile is less than zero
Max bit rate of Mediafile is less than zero
500 General NonLinearAds error. NonLinearAds miss NonLinears

VAST Error Code and messages on Vungle Exchange DSP Demo App:

image1.png

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!

Was this article helpful?