Web API for JSON native Adunits integration
JSON native Adunits let you easily monetize your application (mobile apps or web pages) in a way that's consistent with its existing design and tecnology.
The Instal platform provides web API to retrive all needed informations as JSON data. First of all you need to have an approved native Ad Unit on Instal Platform. You can request a new Adunit from the Adunits section in Install Web console at this link.
To have a native Adunit you need to choose the correct type from the creation page.
Actually there are 2 distinct Mobile Native Adunits dimensions:
- Mobile Native (return 1 single offer)
- Mobile Native List (return multiple offers)
In the next step, you must set the desired adunit name.
On creation of the new adunit, you obtain the Adunit Id and the exact url needed to use the native API.
The following url is just an example of the native api, you must use the correct id!
http://ads.instal.com/api/v1/servead/native?id=4587
The API has the following query parameter:
idrequired 'Adunit id'sc_woptional 'The client display width'sc_hoptional 'The client display high'sc_doptional 'The client display density'slots_noptional and allowed only when adunit dimension isMobile Native List. This parameter indicates the desired number of distinct campaigns in output. The maximum admitted value is10.
To get the right API behaviour you must set the proper user-agent http header for each client platform.
E.g. valid user-agent value is:
Mozilla/5.0 (iPhone; CPU iPhone OS 7_0 like Mac OS X; en-us) AppleWebKit/537.51.1 (KHTML, like Gecko) Version/7.0 Mobile/11A465 Safari/9537.53
The programmatic setting of user-agent http header depends by which platform and API is used.
- On IOS you need to obtain user-agent from a UIWebView object:
// Ask system browser about userAgent
UIWebView *webView = [[UIWebView alloc] initWithFrame:CGRectZero];
NSString *userAgent = [webView stringByEvaluatingJavaScriptFromString:@"navigator.userAgent"];
it's a good idea to cache userAgent value to avoid the creation of UIWebView every request.
Then user agent can be setted into the output request:
NSMutableURLRequest *request=[NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://..."]];
[request setHTTPMethod:@"GET"];
// Set system user agent for this request
[request addValue:userAgent forHTTPHeaderField:@"User-Agent"];
NSOperationQueue *queue = [[NSOperationQueue alloc] init];
[NSURLConnection sendAsynchronousRequest:request queue:queue completionHandler:^(NSURLResponse *response, NSData *data, NSError *connectionError) {
// Responce handling
}];
- On Android if you use the URLConnection api you can apply the following code:
URLConnection cn = new URL("http://....").openConnection();
cn.setRequestProperty("User-agent", System.getProperty("http.agent"));
cn.connect();
The output JSON has the following structure. The most significant elements are inline commented. The example is the output for a Mobile Native List adunit quered with slots_n=3, 3 distinct output campaigns.
{
"adtype": "MOBILE_NATIVE_SLOT_PARAMETRIC_OFFERWALL", //Adunit Type
"impressionurl": "http://ads.instal.com/api/trkpv/?banner_id=&adunit_algorithm=adunit_weighted&adunit_template=MOBILE_NATIVE&cids=25070%2C25962%2C24674&adunit_type=TEXT&adunit_id=577",
// The url to register user adunit impression
"results": 3, //number of returned campaigns
"contents": // contents is an array with the returned distinct campaigns
[{
"rating": null,
// the campaign rating if available
"text": "Amazon Local offers customers awesome deals so they can enjoy",
// the long app campaign description
"destinationurl": "http://ads.instal.com/trkclk/?banner_id=&adunit_format=MOBILE_NATIVE_SLOT_PARAMETRIC_OFFERWALL&cid=25070&adunit_template=MOBILE_NATIVE&adunit_algorithm=adunit_weighted&pid=3&adunit_type=TEXT&adunit_id=577",
// the url to forward on user install click
"title": "Amazon Local - Deals, Coupons",
//the app campaign title
"ctatext": "Install",
//the text to put on the element (button or other widget) to get user click
"adtype": "MOBILE_NATIVE_SLOT_PARAMETRIC_OFFERWALL",
//Ad Unit campaign type. Always equals to the parent element adtype
"iconimage": "http://3cae7b2d0e0c79468053-e3bb5a79eee716a3dc66cfae4bf19cdb.r3.cf2.rackcdn.com/application/icon/3/2bbf68534aab427e1fdcd669fdf84b60.obj",
//url to retrive App campaign icon
"screenshots": [],
//an array with same application screenshots
"promotext": "Get it for free",
//an optional text indicating the application promotion
"mainimage": null
}, {
"rating": 4.4,
"text": "Follow the yellow brick road to riches in THE WIZARD OF OZ\u2122!",
"title": "Hit it Rich! Free Casino Slots",
"ctatext": "Install",
"adtype": "MOBILE_NATIVE_SLOT_PARAMETRIC_OFFERWALL",
"iconimage": "http://49b5af5c747982f45fd7-dec8f175b0901987f30693abc46dc353.r35.cf2.rackcdn.com/cachet/03/af/03afec80ea59231b8f35b7714af5480a.png",
"screenshots": [{
"url": "http://d30c5c35e2b99a6d6cb9-c2a70dab6ccd406d18e6b775b3a3e94b.r95.cf2.rackcdn.com/application/screenshot/10298/d100430a41ea81560ef60b3814d9360c",
"width": 1440,
"orientation": "landscape",
"height": 900
}, {
"url": "http://d30c5c35e2b99a6d6cb9-c2a70dab6ccd406d18e6b775b3a3e94b.r95.cf2.rackcdn.com/application/screenshot/10298/caaff895c6af47ebdc1c54907c43ef85",
"width": 1440,
"orientation": "landscape",
"height": 900
}, {
"url": "http://d30c5c35e2b99a6d6cb9-c2a70dab6ccd406d18e6b775b3a3e94b.r95.cf2.rackcdn.com/application/screenshot/10298/a18e4330b13bcacf8ee97f59dd09115d",
"width": 1440,
"orientation": "landscape",
"height": 900
}, {
"url": "http://d30c5c35e2b99a6d6cb9-c2a70dab6ccd406d18e6b775b3a3e94b.r95.cf2.rackcdn.com/application/screenshot/10298/b9b704afc291f0e3870159419d2c2af7",
"width": 1440,
"orientation": "landscape",
"height": 900
}, {
"url": "http://d30c5c35e2b99a6d6cb9-c2a70dab6ccd406d18e6b775b3a3e94b.r95.cf2.rackcdn.com/application/screenshot/10298/a2b4d5276fd89653040cf8b26183448d",
"width": 1440,
"orientation": "landscape",
"height": 900
}],
"promotext": "Get it for free",
"mainimage": null
}, {
"rating": null,
"text": "***The Web Hit with Over 15 Million Players All Time is now available on iOS!",
"destinationurl": "http://ads.instal.com/trkclk/?banner_id=&adunit_format=MOBILE_NATIVE_SLOT_PARAMETRIC_OFFERWALL&cid=24674&adunit_template=MOBILE_NATIVE&adunit_algorithm=adunit_weighted&pid=3&adunit_type=TEXT&adunit_id=577",
"title": "Dragons of Atlantis: Heirs of the Dragon",
"ctatext": "Install",
"adtype": "MOBILE_NATIVE_SLOT_PARAMETRIC_OFFERWALL",
"iconimage": "http://3cae7b2d0e0c79468053-e3bb5a79eee716a3dc66cfae4bf19cdb.r3.cf2.rackcdn.com/application/icon/3/3b186cb08b38fd57a1ed2ab3570e117f.png",
"screenshots": [],
"promotext": "Get it for free",
"mainimage": null
}]
}
You must remember to call the impression pixel to have the correct reporting on the platform you can find it in the impressionurl returned from the api.
Mobile Native
In case you have selected the Mobile Native you will only get one results and the output will look like this.
Like before you have to honor the impression pixel to have a correct reporting impressionurl the reporting is divided by 2 values, requests and page views. The page views are visible only if you are using correctly the impression pixel, make sure to call it only in case the user see the AD.
{
rating: 4,
destinationurl: "http://mytrackinglive.net/trkclk/?aff_sub_id=&banner_id=&adunit_format=MOBILE_NATIVE&cid=32435&adunit_template=MOBILE_NATIVE&adunit_algorithm=country_weighted&pid=3&adunit_id_s=690%3A1ZOpEC%3A82z7PF-VS_vxZEDVK8jj16k6OV4&adunit_type=TEXT&adunit_id=690",
text: "Turn your mobile device into a FREE, PERSONAL GUIDE - and transform from a tourist into a travel pro. EXPLORE cities, museums, tourist and cultural attractions effortlessly. Be inspired by local stories in audio guides. Seamless social media sharing means the story of your holiday can be easily shared with friends. Enjoy the freedom of turning your vacation into an easy discovery experience - in a growing number of places in the world such as The Netherlands, England, Scotland. Find your personal guidebooks for cities such as Amsterdam, Florence, Istanbul, Barcelona, Prague, London, Munich, Rome, Stockholm and more. ENJOY SUPERPOWERED SIGHTSEEING: • Tap automatically into guided storytelling tours - thanks to location services (GPS). • Share unique facts and special stories with your friends. • Test your knowledge with entertaining quizzes. • Avoid roaming costs before you arrive thanks to easy-to-download content. • Quickly access localised stories with QR code reader & numeric numpad. Easy travel with izi.TRAVEL! ",
impressionurl: "http://ads.instal.com/api/trkpv/?adunit_type=TEXT&adunit_algorithm=country_weighted&adunit_template=MOBILE_NATIVE&slots_number=&filled_slots=1&banner_id=&adunit_id_s=690%3A1ZOpEC%3A82z7PF-VS_vxZEDVK8jj16k6OV4&cids=32435&adunit_id=690",
app_id: "travel.opas.client",
ctatext: "Install",
adtype: "MOBILE_NATIVE",
screenshots: [{
url: "http://3cae7b2d0e0c79468053-e3bb5a79eee716a3dc66cfae4bf19cdb.r3.cf2.rackcdn.com/application/screenshot/12797/8487605506c0e89843c98e00fbaf6313",
width: 506,
orientation: "portrait",
height: 900
}, {
url: "http://3cae7b2d0e0c79468053-e3bb5a79eee716a3dc66cfae4bf19cdb.r3.cf2.rackcdn.com/application/screenshot/12797/d3abe9e77a13d57397907f99912421dd",
width: 506,
orientation: "portrait",
height: 900
}, {
url: "http://3cae7b2d0e0c79468053-e3bb5a79eee716a3dc66cfae4bf19cdb.r3.cf2.rackcdn.com/application/screenshot/12797/a01888f03627b53dd5135ce54c031425",
width: 506,
orientation: "portrait",
height: 900
}, {
url: "http://3cae7b2d0e0c79468053-e3bb5a79eee716a3dc66cfae4bf19cdb.r3.cf2.rackcdn.com/application/screenshot/12797/400217c7677a4a2b07e0284933bf9a4c",
width: 1342,
orientation: "landscape",
height: 900
}, {
url: "http://3cae7b2d0e0c79468053-e3bb5a79eee716a3dc66cfae4bf19cdb.r3.cf2.rackcdn.com/application/screenshot/12797/63546748538be99ca48c7c34c9480d83",
width: 1342,
orientation: "landscape",
height: 900
}],
mainimage: null,
category: "TRAVEL_AND_LOCAL",
title: "izi.TRAVEL tourist audio guide",
iconimage: "http://49b5af5c747982f45fd7-dec8f175b0901987f30693abc46dc353.r35.cf2.rackcdn.com/icon/14/12/31/40d3cada35f2f96e12dc25a3250312ae",
promotext: "Get it for free"
}