Interstitial API

From POKKT DOCUMENTATION
(Redirected from API Interstitial)
Jump to: navigation, search

Ad API - Integration Guide

Last Update: 27th June, 2017


Overview

This document describes the order and flow of an interstitial ad solution between POKKT’s "Ad Platform" and a "Supply Partner". In essence, it entails the process that needs to be followed by the "Supply Partner" to integrate their services with POKKT’s demand.

Technical Details

Request URI

A GET request needs to be originated to POKKT server to initiate the ad request. The Partner herein is required to send a request to the below endpoint which in turn will respond with one or more ad meta in a JSON response.

Endpoint

https://vdo.pokkt.com/api/AdServer

Full Parameters

https://vdo.pokkt.com/api/AdServer?appId={{{app_id}}}&appName={{{pub_app_name}}}&ad_format=1&response_format=0&device_id={{{device_id}}}&advertisingID={{{aaid/idfa}}}&ip={{{ip}}}&ua={{{browser_user_agent}}}&limitedTracking={{{ad_tracking_disabled}}}&category={{{pub_app_store_category}}}&app_bundle_name={{{app_bundle_name}}}&u13={{{u13}}}&idfa_md5={{{md5_ifa}}}&idfa_sha1={{{sha1_ifa}}}&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}}}&swidth={{{width}}}&sheight={{{height}}}

Parameters Explained

PARAM DESCRIPTION MANDATORY RECOMMENDED
appId Your unique App ID (available in POKKT dashboard) Yes
appName App Name(e.g. Metal%20Gear%20Dawn) Yes
ad_format Ad Format (1 - Banner, 3 - Interstitial) Yes
response_format APIResponse(0 - JSON response, 2- HTMLmarkup) 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 (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
idfa_md5 MD5 hashed IDFA Yes
idfa_sha1 SHA1 hashed IDFA
aid_md5 MD5 hashed Advertising ID Yes
aid_sha1 SHA1 hashed Advertising ID
app_storeurl URL encoded Play or 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
Swidth Width of the expected banner Yes
sheight Height of the expected banner Yes

Notes:

  1. It is highly advocated that you pass all the above RECOMMENDEDparameter values alongside the MANDATORYones, 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. You can add any missing or additional parameter to the query string separated by ampersand (&).

Successful Response

A successful response is either an HTML mark-up which expects the ad to be delivered as is or a JSON response depending on what you choose in response_format.

Example Responses

HTML response (response_format=2)
<p><a href="https://clk.pokkt.com/tracking/3e104fac"> <img
src="https://cdn.xyz.com/pokkt/3e104fac.gif" /></a></p>
JSON response (response_format=0)
{
"status": "1",
"message": "Success",
"response_format": 0,
"Content-Type": "application\/json",
"others": [
{
"offer_id": "5031",
"campaign_form_type": "interstitial",
"width": 480,
"height": 640,
"interstitial_creative": "<html>...<\/html>",
"creative_format": "MRAID2",
"image_url": "http:\/\/assetscdn.s3.amazonaws.com\/assets\/a_20160307123416.jpg",
"impression_urls": [
"https:\/\/vdo.pokkt.com\/api\/vt?track_id=ai1&appId=17&offer_id=51&event=6&"
],
"click_urls": [
"https:\/\/vdo.pokkt.com\/api\/vt?track_id=ac1&appId=17&offer_id=51&event=6&"
]
}
]
}

Name/Value Pairs Explained

  • interstitial_creative: This will contain banner creative in the HTML+JS format. Partners may load the creative directly in a webview container
  • image_url: URL for the image banner
  • impression_urls: The impressions trackers which needs to be fired by partner when the image ad is loaded and visible
  • click_urls: The trackers that needs to be fired by partner when users click on the image ad
  • creative_format: This will indicate if the ad in response is NON_MRAID or MRAID1 or MRAID2.

Note: All the above fields will be sent in the response (if JSON response is chosen). The partner can choose which to pick depending on how they wish to integrate. In case of HTML response you will have a header Creative-Format to indicate the ad in response is NON_MRAID or MRAID1 or MRAID2.

Error Responses

The POKKT ad server responds with a blank JSON array 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 or if it comes across different issues.

Example Error Responses

Error response in case of No Fill (no matching ads to fill)
[]
Error response in case of invalid or incomplete parameters
{
"status":"0",
"message":"invalid package\/key",
"others":[],
"vc":"0"
}

FAQS

Q. Does POKKT support XML response?

A. Currently the response output is restricted to an JSON and HTML mark-up only as far as non-video display ads go. Video Ad response is VAST XML (kindly request your POC for that document, if you wish to integrate Video Ads). We will update this document when support for other output formats are made available.

Q. Does POKKT support regular banners (for eg. 300x50)?

A. POKKT currently supports full screen interstitials ads with 16:9 or 5:4 ratios (reversible ratios for portrait). The HTML banners are responsive in nature. We will update this document when support for other ad formats are made available.

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

A. POKKT and its 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 partners who 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) describes this in detail.