Interstitial API

Contents

  • 1 Ad API - Integration Guide

    • 1.1 Overview

    • 1.2 Technical Details

      • 1.2.1 Request URI

    • 1.3 Name/Value Pairs Explained

    • 1.4 Error Responses

      • 1.4.1 Example Error Responses

    • 1.5 FAQS

Ad API - Integration Guide

Last Update: 20th May, 2021

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

Parameters Explained

PARAMDESCRIPTIONMANDATORYRECOMMENDED

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

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. You can add any missing or additional parameter to the query string separated by ampersand (&).

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

  5. 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

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.

PreviousAPI GuideNextVast Video API

Last updated

Copyright © POKKT 2022. All Rights Reserved