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

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.

Last updated

Copyright © POKKT 2022. All Rights Reserved