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
Parameters Explained
Notes:
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.
All parameter values must be URL Encoded as applicable
You can add any missing or additional parameter to the query string separated by ampersand (&).
All the traffic with gdpr_applicable=1 will be filtered.
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
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
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