Vast Video API

From POKKT DOCUMENTATION
Jump to: navigation, search

Vast Video API - Integration Guide

Last Update: 27th June, 2017


Overview

POKKT is a mobile video advertising and monetization platform that offers real Rewards to users for availing Advertising Offers. POKKT helps it’s partners to significantly increase revenues by converting non-paying users into loyal transacting customers.

This document describes the order and flow of a video ad solution between POKKT’s ”Video Ad Platform” and a “Supply Side Platform”. In essence, it entails the process that needs to be followed by the “Supply Side Platform” to integrate their services with POKKT’s “Video Ad Platform”.

Technical Details

Request URI

A GET request needs to be sent to POKKT server to initiate the video request. The Partner herein is required to send a request to the below URI which in turn will respond with a VAST tag.

Code

http://vdo.pokkt.com/api/AdServer?appId={{{app_id}}}&appName={{{pub_app_name}}}&response_format=1&device_id={{{device_id}}}&advertisingID={{{aaid}}}&ip={{{ip}}}&ua={{{browser_user_agent}}}&limitedTracking={{{ad_tracking_disabled}}}&category={{{pub_app_store_category}}}&app_bundle_name={{{app_bundle_name/web_domain}}}&ios_app_id={{{ios_appid}}}&u13={{{u13}}}&aid_md5={{{md5_aaid}}}&aid_sha1={{{sha1_aaid}}}&app_storeurl={{{pub_app_store_url}}}&age={{{age}}}&gender={{{gender}}}&latitude={{{latitude}}}&longitude={{{longitude}}}&categoryIab={{{category_iab}}}&connType={{{connection_type}}}&deviceCategory={{{device_category}}}&osName={{{os_name}}}&osVersion={{{os_version}}}&appVersion={{{app_version}}}&cacheBreaker={{{cache_breaker}}}&referral={{{referral_url}}}&ecs={{{ECS_SUPPORTED}}}&vd_min={{{video_duration_min}}}&vd_max={{{video_duration_max}}}&swidth={{{width}}}&sheight={{{height}}}

Parameters Explained

PARAM DESCRIPTION MANDATORY RECOMMENDED
appId Unique App ID (available during integration) Yes
appName App Name(e.g. Metal%20Gear%20Dawn) Yes
ad_format Ad Format (0 for VAST) Yes
response_format Ad medium indicator (for internal POKKT use) = 1 Yes
device_id OS ID or Device ID Yes
advertisingID Google Advertising ID or iOS IDFA Yes
ip IP address Yes
ua User Agent Yes
limitedTracking Do Not Track or DNT (e.g. 1 for tracking disabled, 0 for enabled) Yes
category App Store Category Name (e.g. Finance) Yes
app_bundle_name Android Package Name or iOS Bundle ID or mobile web domain (e.g. com.rage.metalgeardawn) Yes
ios_app_id iOS App ID Yes
u13 App targeted to children under 13 years (1 for Yes, 0 for No) Yes
aid_md5 MD5 hashed Advertising ID yes
aid_sha1 SHA1 hashed Advertising ID
app_storeurl App Store URL Yes
age User’s age(e.g. ‘24’) Yes
gender User’s gender(e.g. ‘m’) Yes
email_address User’s email
latitude Device Latitude(e.g. -7.5481032) Yes
longitude Device Longitude(e.g. 35.2835043) Yes
categoryIab IAB Category Code(e.g. IAB1, IAB31 etc.) Yes
connType Connection Type (Numeric value e.g. 0-Unknown, 1-Ethernet, 2-Wifi, 3-Cellular-Unknown Generation, 4-2G, 5-3G, 6-4G/LTE) Yes
deviceCategory Smartphone, Tablet, Smartwatch etc. (codes – section 5.17) Yes
osName OS Name or Platform (e.g. iOS, Android, Windows etc.) Yes
osVersion OS Version (e.g. 4.4.4, 5.0.1 etc.) Yes
appVersion Publisher App Version(e.g. 1.0.1, 2.7 etc.) Yes
cacheBreaker Allows ad server to identify cached ads(e.g. cb739ade24b) Yes
referral Referring page/URI Yes
ecs End Card Support (e.g. 1 for Yes, 0 for No)
vd_min Expected minimum duration of video
Vd_max Expected maximum duration of video
swidth Width of the Player Yes
sheight Height of the Player Yes

Notes:

  1. It is highly advocated that you pass all the above RECOMMENDEDparameter values alongside the MANDATORYones, ones, as the premium and high paying ad sources need the above parameters to classify and target users. These campaigns in return furnish very high ECPMs.
  2. All parameter values must be URL Encoded as applicable

Response

In response to the above ad request (with all requisite macros values), POKKT’s ad server will respond with a standard VAST XML response.

Successful Response

A successful response is a standard VAST 2.0 XML tag with all the events and associated trackers. Refer to IAB VAST guidelinesfor more information.

Example (barebones linear VAST tag with End Card Example) [updated]

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="2.0">
<Ad id="XXX">
<InLine>
<AdSystem>Pokkt>/AdSystem>
<Creatives>
<Creative>
<Linear>
<VideoClicks>
<ClickTracking>>![CDATA[...]]>>/ClickTracking>
</VideoClicks>
<TrackingEvents>
<Tracking event="firstQuartile">>![CDATA[...]]>>/Tracking>
<Tracking event="midpoint">>![CDATA[...]]>>/Tracking>
<Tracking event="thirdQuartile">>![CDATA[...]]>>/Tracking>
<Tracking event="complete">>![CDATA[...]]>>/Tracking>
<Tracking event="start">>![CDATA[...]]>>/Tracking>
<Tracking event="skip">>![CDATA[...]]>>/Tracking>
<Tracking event="mute">>![CDATA[...]]>>/Tracking>
<Tracking event="unmute">>![CDATA[...]]>>/Tracking>
<Tracking event="creativeView">>![CDATA[...]]>>/Tracking>
</TrackingEvents>
<Duration>00:00:30>/Duration>
<MediaFiles>
<MediaFile>>![CDATA[...]]>>/MediaFile>
</MediaFiles>
</Linear>
</Creative>
<Creative>
<CompanionAds>
<Companion>
<HTMLResource>http://abc/test.html>/HTMLResource>
<CompanionClickThrough>>![CDATA[...]]>>/CompanionClickThrough>
<CompanionClickTracking>>![CDATA[...]]>>/CompanionClickTracking>
<TrackingEvents>
<Tracking event="close">>![CDATA[...]]>>/Tracking>
<Tracking event="creativeView">>![CDATA[...]]>>/Tracking>
</TrackingEvents>
</Companion>
<Companion>
<StaticResource>http://abc/test.gif>/StaticResource>
<CompanionClickThrough>>![CDATA[...]]>>/CompanionClickThrough>
<CompanionClickTracking>>![CDATA[...]]>>/CompanionClickTracking>
<TrackingEvents>
<Tracking event="close">>![CDATA[...]]>>/Tracking>
<Tracking event="creativeView">>![CDATA[...]]>>/Tracking>
</TrackingEvents>
</Companion>
</CompanionAds>
</Creative>
</Creatives>
<AdTitle>>![CDATA[Ad Name]]>>/AdTitle>
<Impression>>![CDATA[...]]>>/Impression>
<Error>>![CDATA[...]]>>/Error>
</InLine>
</Ad>>/VAST>

Error Responses

The POKKT ad server responds with a blank VAST tag for cases where there is no ad to fill. The server will respond with a JSON error string in case the app ID isn’t valid.

Examples

Error response in case of No Fill (no matching ads to fill)
<VAST version="2.0"></VAST>

Error response in case of invalid or incomplete parameters
{"status":"0","message":"invalid package\/key","others":[],"vc":"0"}

FAQS

Q. What happens if we don’t send one or more of the mandatory parameters?

A. POKKT and it’s advertising partners absolutely need all the mandatory parameters to be passed through and cannot guarantee fill if you are unable to provide all the mandatory parameters.

Q. What happens if we are unable to send one or more of the recommended parameters?

A. POKKT advocates that you send in all the recommended parameters mentioned in this document. POKKT works with top advertisers and advertising demand partnerswho predominantly drive higher ECPMs for your apps provided pertinent information is available to them.

Q. How secure is the user data passed in the API calls?

A. POKKT is committed to protect the privacy of the users who access its platform. POKKT’s Privacy Policy statement (Privacy Policy) describesthis in detail.