VAST API

Last updated 23/8/2018

Video ads have conquered the mobile space, winning the hearts of billions of users across the world. It wasn’t a surprise when apps, both the global giants and the rising stars, embraced the new opportunity. Video ads allow app developers to tell their unique story and give the users a sneak peek of what the app is about delivering a great user experience.

VAST is an XML-based API response format, standard for video ad delivery. It allows publishers to integrate different demand solutions without developing custom integrations for each partner. The basic integration requires video creative, impression reporting, video events reporting, a click-through link. And, voila, you can easily tap into the app video world, securing great user experience and unmatched monetization performance.

Appnext Account & ID

1. Register for an Appnext Account
You must first create an account with Appnext to be able to use this ad unit’s features.
If you do not have an Appnext account, copy the following URL to the browser: https://www.appnext.com and sign up

2. Get a Unique ID.
To get started, add a new App via the Appnext Self-Service Platform, then copy the Placement ID, which can be found in your account at:
Apps -> Settings Icon-> Settings & Placements -> Placement ID (make sure to copy the Placement ID for both Android and iOS apps).

Getting started with Appnext VAST API

Data returned in Appnext VAST API response

Appnext VAST API returns raw-data of Android or iOS apps, promoted through campaigns by advertisers in the Appnext platform, which specifically target your app placement. Data includes advertiser’s app creative content, current bid, tracking link, ad-serving weight, etc.

Requesting app data

A “Placement ID”, which is a unique key generated by the Appnext platform, must be added to the VAST API call in order to receive apps data.
Requesting the VAST API with an Android Placement ID will return Android targeted campaigns and requesting it with an iOS Placement ID will return iOS targeted campaigns. Only one OS can be called in a single API call.

Campaign inventory

Each VAST API request will return data for a single app promotion campaign. By default, the targeted GEO will be determined as the client-side GEO. For example: when requesting the API from a server, located in the US, the API will return a campaign that is targeting US users.

Campaigns Status

App campaigns constantly change during the day by advertisers. Campaigns are being paused, activated, creative change and bid increase or decrease to compete on your placements via the platform.

Every campaign running has a daily cap (budget). Once a campaign has depleted its daily cap it will be paused until the following day. Campaign that was paused, might not redirect to the store, and will not be eligible for payment.

An JSON file is returned with In case of Capping /Geo Targeting/end of banner inventory/No ads

Sample JSON:
{
empty:""
}

Measurement and reporting

Impressions count

Counting impressions accurately is important for performance calculations.
Every VAST API response will include an impression URL, for example:

<Impression>
https://global.appnext.com/pView.aspx?b=12345&z=12345&c=12345
</Impression>

Counting Clicks and installs

Appnext counts a click whenever the link, provided by the API for each creative asset / component, is clicked.

🚧

Important note:

Do not preload / pre-fetch the urlApp links, as this will generate additional costs to our Advertisers who are using 3rd party tracking solutions for conversion tracking.

Postbacks

A Postback (also known as a callback) is a server-to-server call made by Appnext’s server to a publisher’s server with the purpose of notifying him of a conversion (install) made through his app / website.

You may choose to receive up to 3 parameters in each Postback call:

1. Postback parameter – any custom parameter
2. Revenue – the CPI revenue generated for the install
3. Package – the app package
4. IP – IP of the user who installed the app

Passing a Postback parameter

You can pass Postback data / values for each offer returned by the API. Once a successful install is made, Appnext will call your Postback URL, with the Postback value passed.
In order to pass Postback data / values, make sure to add them to the “&pbk={value}” parameter to the API call.

Appnext will send Postbacks from these IP addresses: 23.21.212.42, 54.204.84.86 and 184.73.163.42 make sure to white-list all of these addresses.

Receiving Postbacks

In order to receive Postbacks, you should provide Appnext with a Postback URL. The Postback URL is the endpoint at your server or third-party tracking service, to which we will be sending the Postback.

If you are interested in receiving a Postback, please make sure to set the postback URL in your account, under your app’s settings.

Sub ID Reporting

Media Partners (such as: ad networks, content networks etc.) are required to pass their publisher’s Sub ID when calling the API.
In order to pass the SubID, add a “&subid={value}” to the API call.

GAID / IDFA

Passing Appnext the Advertising ID / IDFA is mandatory when serving ads in mobile apps.
In order to pass the Advertising ID / IDFA, add a &did={value} to the API call.

🚧

GDPR/Opting out from ads-retargeting

If the user opted out from ads-retargeting, or if the user has not provided consent under the GDPR rules, do not pass the GAID/IDFA string. Just send empty value in the did parameter

Package name

Passing the app package name is mandatory when serving ads in mobile apps. When using Android apps - please pass the package name. When using iOS apps - please pass iTunes tracking ID (number). The value is passed in the "&packageId" parameter.

Requesting raw ad data for Android and iOS

VAST API base URL (request):

https://global.appnext.com/offerWallApi.aspx?id=PLACEMENT_ID&type=vast&vast_ver=3.0&tid=vast&cv=1&duration=DURATION&did=ADVERTISING_ID&packageId=PACKAGE_NAME&comp_icon=app_icon&comp_title=app_title&comp_desc=app_description&comp_wide_img=app_wide_image&comp_rating=app_rating&comp_downloads=app_number_of_downloads&comp_btn_text=install_button_title

API request Parameters:

🚧

Important notes:

1. If you are making the call from a server side or a mediation, please contact our support team before making the first call.
2. Each parameter added to the API string should be added with the “&” symbol. This symbol is used in order to differentiate one parameter from another.
3. When using multiple categories, make sure to use the following format:
   Categories with 2 words, for example: Arcade & Action must be encoded in the following format: Arcade%20%26%20Action

Response of raw ad data

<VAST version="3.0">
<Ad id="100880">
<InLine>
<AdSystem version="1.0">Appnext VAST</AdSystem>
<AdTitle>Knights & Dragons</AdTitle>
<Impression>
https://admin.appnext.com/pView.aspx?b=100880&z=25526&c=78249
</Impression>
<Description>
Knights & Dragons is a non-stop action role playing game.
</Description>
<Pricing>"cpi,","USD","2.98"</Pricing>
<Error>
https://admin.appnext.com/tp12.aspx?ads_type=VAST&tid=VAST&vid=1&pid=0fa643ba-a3e5-4f01-bf49-89354fbd0562&ref=error&bid=100880&cid=78249&callback=ecdca49b-c2c1-45fa-87a3-429da1d9b530
</Error>
<Creatives>
<Creative id="100880">
<Linear>
<Duration>00:00:30.000</Duration>
<VideoClicks>
<ClickThrough>
<![CDATA[
https://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test
]]>
</ClickThrough>
</VideoClicks>
<TrackingEvents>
<Tracking event="start">
<![CDATA[
https://admin.appnext.com/tp12.aspx?ads_type=VAST&tid=VAST&vid=1&pid=0fa643ba-a3e5-4f01-bf49-89354fbd0562&ref=play_video&bid=100880&cid=78249&callback=8d801093-a18d-4bfb-a961-eabc686ecda5
]]>
</Tracking>
<Tracking event="complete">
<![CDATA[
https://admin.appnext.com/tp12.aspx?ads_type=VAST&tid=VAST&vid=1&pid=0fa643ba-a3e5-4f01-bf49-89354fbd0562&ref=video_ended&bid=100880&cid=78249&callback=2c03b9f3-22eb-4d56-baf7-0d4b71283f12
]]>
</Tracking>
</TrackingEvents>
<MediaFiles>
<MediaFile delivery="progressive" type="video/mp4" width="640" height="360" bitrate="500" scalable="true" maintainAspectRatio="true">
<![CDATA[
https://appnext.hs.llnwd.net/banner/video/video-100880-30_o.mp4?rnd=1458234131
]]>
</MediaFile>
<MediaFile delivery="progressive" type="video/mp4" width="320" height="180" bitrate="500" scalable="true" maintainAspectRatio="true">
<![CDATA[
https://appnext.hs.llnwd.net/banner/video/video-100880-30.mp4?rnd=1458234131
]]>
</MediaFile>
</MediaFiles>
</Linear>
</Creative>
<Creative id="100880_companion" adId="100880">
<CompanionAds required="none">
<Companion id="app_icon" width="512" height="512">
<StaticResource creativeType="image/png">
<![CDATA[
https://appnext-a.akamaihd.net/banner/r5OkEL3JUHUIZ7j_square.png
]]>
</StaticResource>
<CompanionClickThrough>
<![CDATA[
https://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test
]]>
</CompanionClickThrough>
</Companion>
<Companion id="app_title" width="0" height="0">
<HTMLResource>
<![CDATA[ Knights & Dragons ]]>
</HTMLResource>
<CompanionClickThrough>
https://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test
</CompanionClickThrough>
</Companion>
<Companion id="app_description" width="0" height="0">
<HTMLResource>
<![CDATA[
Knights & Dragons is a non-stop action role playing game.
]]>
</HTMLResource>
<CompanionClickThrough>
https://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test
</CompanionClickThrough>
</Companion>
<Companion id="app_wide_image" width="1200" height="628">
<StaticResource creativeType="image/png">
<![CDATA[
https://appnext-a.akamaihd.net/banner/r5OkEL3JUHUIZ7j_rectangular.png
]]>
</StaticResource>
<CompanionClickThrough>
<![CDATA[
https://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test
]]>
</CompanionClickThrough>

</Companion>
<Companion id="app_rating" width="0" height="0">
<HTMLResource>
<![CDATA[ 4.4 ]]>
</HTMLResource>
<CompanionClickThrough>
<![CDATA[
https://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test
]]>
</CompanionClickThrough>
</Companion>
<Companion id="app_number_of_downloads" width="0" height="0">
<HTMLResource>
<![CDATA[ 10000000+ ]]>
</HTMLResource>
<CompanionClickThrough>
<![CDATA[
https://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test
]]>
</CompanionClickThrough>
</Companion>
<Companion id="install_button_title" width="0" height="0">
<HTMLResource>Install</HTMLResource>
<CompanionClickThrough>
<![CDATA[
https://admin.appnext.com/appLink.aspx?b=100880&e=25526&d=0aaaaaaaa-bbbb-cccc-1111-222222220000&subid=12345&q=test
]]>
</CompanionClickThrough>
</Companion>
</CompanionAds>
</Creative>
</Creatives>
</InLine>
</Ad>
</VAST>

API response Parameters

App Categories

Make sure to encode (%20) categories with more than 1 word, example: Travel%20%26%20Local