Vast Video API

Contents

  • 1 Vast Video API - Integration Guide

    • 1.1 Overview

    • 1.2 Technical Details

      • 1.2.1 Request URI

    • 1.3 FAQS

Vast Video API - Integration Guide

Last Update: 20th May, 2021

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}}}&gdpr_applicable={{{gdpr_applicable}}}&gdpr_consent={{{gdpr_consent}}}&vv={{{viewability_vendors}}}&p_sco={{Supply_Chain_Obj}}

Parameters Explained

PARAMDESCRIPTIONMANDATORYRECOMMENDED

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

gdpr_applicable

GDPR relevant (1 for True, 0 for False)

Yes

gdpr_consent

GDPR permission (String value True/False or Custom consent string)

Yes

vv

Viewability vendors comma seperated list (String value, one or more of possible values -- integralads.com,moat.com,comscore.com,viewability.withgoogle.com,sizmek.com,adform.com,whiteops.com)

No

Yes

p_sco

Supply Chain Object (String value)

Yes

Notes:

  1. It is highly advocated that you pass all the above RECOMMENDED parameter values alongside the MANDATORY 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

  3. All the traffic with gdpr_applicable=1 will be filtered.

  4. Supply Chain Object is composed of two items; the SupplyChainObject properties and the SupplyChainNode array. These two items are separated by a bang (“!”) as follows

    • {SupplyChainObject}!{SupplyChainNode array}

      • SupplyChainObject consists of two properties version and complete separated by comma(,)

      • SupplyChainNode consists of domain name of the SSP, Exchange etc (asi), identifier associated with the seller or reseller account (sid), OpenRTB RequestId (rid), name of the company/entity (name), business domain name of the entity (domain) and Placeholder for advertising-system specific extensions to this object(ext [optional]). All these properties should be separated by comma(,) and if there is more than one node, each must be separated by a bang (“!”) character. For example,

      • Single Hop Chain - 1.0,1!xyzexchange.com,4321,1,bid-request-1,publisherx,publisherx.com

      • Multiple Hop Chain - 1.0,1!xyzexchange.com,4321,1,bid-request-1,publisherx,publisherx.com!xyzexchange2.com,1234,1,bid-request-2,intermediaryx,intermediaryx.com

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 guidelines for 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.

PreviousInterstitial APINextGratification API

Last updated

Copyright © POKKT 2022. All Rights Reserved