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 set the 'Dimensions' property to one in 'Mobile Native Ads' subsections.

Choosing mobile adunit dimension

Actually there are 2 distinct Mobile Native Adunits dimensions:

  • Mobile Native (return 1 single offer)
  • Mobile Native Json slot parametric offerwall (return multiple offers)

When you save the new ad unit you obtain an Adunit Id to use in the api url. The exact url to use is reported on the same adunit page:

Choosing mobile adunit dimension

The url to use is like this with the appropriate Adunit id value:

 http://ads.instal.com/api/v1/servead/native?id=575

The url has the following query parameter options

  • id required 'Adunit id'
  • sc_w optional 'The client display width'
  • sc_h optional 'The client display high'
  • sc_d optional 'The client display density'
  • slots_n optional and allowed only when adunit dimension is Mobile Native Json slot parametric offerwall. This parameter indicates the desired number of distinct campaigns in output. The maximum admitted value is 10.

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 Json slot parametric offerwall 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"
}