This is the help page for the integration with our ad serving engine, the OfferEngine, and your application. Remember that you will need to have an affiliate ID in order to track your links, but you can testdrive the library without it.

SIGN UP

For any doubts, questions, or asistance, contact us.

API endpoint, v002

This is the documentation for the API version v002. You can check the legacy docs for v001.

This is the same API our Android and iOS libraries - so anything we do via the libraries is possible with your own code too. The normal use of the API is to send a request to the endpoint with the required parameters (check below) and the desired optional ones, and you can expect a JSON-formatted response in return.

If you implement the API with custom code, there are some things you need to take into account:

  • you must at least display one image, for us to be able to track the impression of the ad - or ping the image URL.
  • you should indicate that the ads are so in some way, to not trick the users: via an "Ad" icon "Sponsored", etc.
  • you should open the "click_url" only (and only when) the user has clicked the ad
  • we recommend you to update the ads frequently: when the user comes back to the screen or app, when the user refreshes the data in the screen or webpage, etc.
  • Request

    We provide you libraries to download and display the ads in different platforms (iOS, Android and mobile websites), but we also provide you the JSON endpoint for custom implementations.

    http://getnativeads.pocketmedia.mobi/apiV002/ow.php?output=json&os=android&version=6.0&model=SGS6&token=1234&placement_key=tokenkey&limit=3
    Note: you can also use the secure endpoint, via https.

    The parameters list are the following:

    • * output (required): valid values are json and html (mind the caps). For native ads the output should be specified as JSON.
    • limit (optional): the number of ads to be served on response to this request. Default value is 10.
    • * os (required): operative system. Valid options: ios / android / web.
    • * version (required): operative system version, in a readable format (such as 4.2, 7.3, 6.0...)
    • * token (required): the unique identifier for the user. It must comply with Apple and Google guidelines for advertising. Explained later how to retrieve it per platform.
    • * placement_key (required): token identifier for the ad placement. It can be retrieved in the user panel (http://third-party.pmgbrain.com/, Apps/Websites > App > Placements)
    • image_type (optional): in case some specific image types are wanted for the placement, the offers can be filtered to be sure they contain the desired image types. Multiple types can be specified, separated by commas (e.g.: icon,banner). The possible values are:
      • icon
      • hq_icon
      • banner
  • Response

    The response for the ads request will be a JSON file containing a list with the offers and their assets, such as:

    [
       {
          "id": "77537",
          "campaign_name": "AnastasiaDate: Date & Chat App",
          "campaign_description": "Meet charming, funny & beautiful international women with the top AnastasiaDate dating app",
          "app_store_url": "https://play.google.com/store/apps/details?id=com.itonline.anastasiadate",
          "click_url": "http://offerwall.12trackway.com/save-click.php?campaign=77537&impression=77620976&token=XYZ",
          "action_text": "Install",
          "campaign_image": "http://offerwall.12trackway.com/image-world/5d08489d3d4540ee96a49c650234e397f24b36ddd75f047b931c71d4dec804d28d0ff70fd5474db0487f14fbf6751b4a2a8647dbe10bc2951a353dd2abc5b2b56a6133ce7c19974854a16e07c505062894aaf61c8dc662c9729a1ab56fc9f3ce523ccf8a08b16f30283c932fa8d6c43ed2b2cf970fa41333f04f92cf1a553a5944753543f65e97ca58169b8cd9f4359d6137377cc56354b112a96c8ab4a44039bdf9b0e62a294284ea4270b8c64ec9b23b4e070297806a4d80c2a2ec8c15e4b00253c896ec8739f818cea50d8adb160b9b88e998afe667934fb6bbbb408ee774.jpg",
          "images": {
             "icon": {
                "url": "http://offerwall.12trackway.com/image-world/1f68b34b9a46d11beca1d7f9dc3462fe757601b45e63e3886afd4d4ec599f1a6f9df227eff322afe68b765e5a44e8fb74e37e79511f8ed4a2e825aec22a07a9ce9d0436a6c3fba2aa8f4d1526402a219a25530f816c84c20670eeeded92d96011645aafc83a0c4817f16cbf1cc1c0076744f05341f115f709d7af449fd1a4af6a3ba05a0bb796eedb67a0b0aeadd761a808b69728618f8433740f2b1fce864c2b03ce57eb0b44ae0d380d39a1520c68739e33bbffcb4c89c6725472f32a29ff95fb777d53c2950aed1b37bf508984fc9c330ebc432b6de0f2ed595cfd628d46b.jpg",
                "width": "80",
                "height": "80"
             },
             "banner": {
                "url": "http://offerwall.12trackway.com/image-world/30124b3a816f9f14ede7da0c24a720b0ac890833728ab0f48ba8607d944e064d1c4d22f7cf90b61cc0ef19577849ad6c9b8bd6e4d60f6b6ea36005aa59e0cef608469a58540d1e36a86281c30627547a099577fe0ec56e54fc8b207733251342abb34e574210c1a88e3e5cc68481464fb1c90e05a491df66c7ca03da24e96e2e57f8d2464a25f49240d9ddb86d017b239771c930ab33f2153c07c5e579bac38d079880f7f7d1dee2873e666acce6f3ce879e244bda14b533404f71e9c3bbe4a67483c68f7eddc1489649c5e3ac262936c006d3799896d2a6d19df28b9224fa7a.jpg",
                "width": "728",
                "height": "90"
             }
          },
          "open_in_browser": false
       }
    ]

    The objects received in the JSON structure are:

    • id: this is a numeric unique identifier. No need to show it, can be used to tell offers appart.
    • campaign_name: the title of the campaign. Should be displayed next to the icon of the app, as it's the most representative information about the campaigns.
    • app_store_url: this is the preview url. It will be a Google Play URL in case of Android apps, a iTunes URL in case of iOS, and a web URL in case it's another kind of offer.
    • click_url: this is a very important piece of information. This URL needs to be invoked when the user clicks in the ad - and it will enable us to know that that specific user was coming from your app/website.
    • action_text: the text that the call to action button should have. It can have values such as "Download", "Install", "Try now", "Know more", etc.
    • campaign_image: the default image for the campaign. In the next object you will find more graphical elements to use - but the default image is ready to be used. It's important to display at least one image, as it is the way we can track the impressions for the offers.
    • images: an estructure containing more images. It can contain images of the following types (but they won't always be available - so check for their existance, or filter the request via the "image_type" request parameter)
      • icon: square icon for the app, the default asset to display
      • hq_icon: same as the icon, but higher resolution
      • banner: a larger image with non-square proportions. Can be vertical or horizontal.
    • open_in_browser: in some cases the offers are app installs (for Google Play and iTunes) - and the libraries take care of hiding the redirections until the last url is reached, after the user clicks in the "click_url". In case the URL can be opened straight away (as it won't be an app install), this value will be true, meaning the click url should be opened straight away in the system's browser.

Obtaining a user token

  • When using the native libraries for iOS and Android this process is done automatically. In case you want to implement the API communication manually, you must also handle the token retrieval for the platform.

    iOS

    For Apple devices it is mandatory using the Apple Advertising Identifier. This token is retrieved trough the ASIdentifierManager class.

    Apple Documentation

    Android (Google Play)

    For Android devices using Google Play Services it is mandatory to use the Advertising Identifier Provided by Google Play:

    Google Documentation

    Android (without Google Play)

    In devices without Google Play Services, such as apps in alternative marketplaces (Amazon, Baidu, etc.) it is possible to use an alternative identifier:

    • ANDROID_ID: consists in a 64-bit number randomly generated on the 1st boot of a device. Usually it is not modified during the lifetime of the device.
    • DEVICE_ID: returns an identifier such as the GSM IMEI, or the MEID or ESN for CDMA phones. Can be null.
    • Mac Address: uniquely identifies the wireless network adapter of the device. Can be retrieved through the WifiManager class.