, ,

Offer’s API for App Promotion.

If you’re in the world of App Promotion (as we are, in Geenapp) and you do not work with a platform that has its own API -and you have to create it-, it’s likely that you’re wondering what the person who’s going to receive the data needs. There are various possibilities (try to cover most of them), but the truth is you must adapt the API with the data that you have.

Also, keep in mind that when an offer is made to the advertiser, you must ask for a minimum of elements:

  • App and its URL on Google Play / iTunes.
  • Total Money / per installation.
  • Limitations (can be given by the customer or included if you have a monthly budget and you want to maintain installations throughout the whole period).
  • Quality Type.
  • Countries and devices.

From here you can create multiple campaigns based on combinations of these data. When creating an API as an agency, we must consider the following items (to provide simple and good service):

  1. With one call to an URL everything has to be processed.
  2. You can make one call for each offer.
  3. There must always be at least one offer (even if it’s just one test App or Campaign with a Price 0).

Another important element that helps us simplify this process is to make an API REST, with only one validation identifier (something like an API key). This system works for any programming language and it’s also verifiable from an Internet browser.

Starting with the data to be published. The basics are:

  • Offer Identifier [OfferId]: Normally, a unique number that identifies unequivocally one offer.
  • Job Title [name]: The title of the offer, usually accompanied with the App, countries’ ID’s, devices…
  • Money [payout]: The amount to be paid for each installation or action.
  • Currency [currency]: The ISO 4217 of the currency. Something like EUR or USD. In this world, offers are usually in euros or dollars, hereby any other currency often limits the promotion.
  • Country [country]: Normally, this is an array (or text, separated by commas) with the list of countries in ISO 3166-2 like ES, GB, DE…
  • Devices [device]: This can be done in many ways, but the simplest is an array that includes concepts such as iPhone, iPad, Android Phone, Android Tablet… Normally it’s best not to mix systems and separate iOS and Android Offers.
  • Quality [incent]: An indicator that clearly identifies if the offer is incentivized (low quality traffic) or not incentivized (high quality). The value can be Boolean with 0 and 1.
  • Limitation of volume [capping]: Here, you have various options, because capping can be per day, per month or total. The simplest option is to have 3 values: [capping_day], [capping_month], [capping_total], which will have by default null, except where there is another one available. Also, if possible, it is also interesting to determine the available capping at that moment, for example 3 more values:[capping_day_left], [capping_month_left], [capping_total_left]. This capping should be reset at 00:00 UTC each day / month.
  • Preview URL [preview]: URL where you can visualize where the user will arrive when clicking. It can be a Google Play, iTunes URL…
  • Offer URL [url]: URL where you will send your traffic. No need to add extra parameters. Add just this URL in order for it to work (although we could add an attachment in which we’ll provide extra parameters… to be explained further).
  • Offer Description [description]: It is not necessary to give a description of the App, but a key element of the offer that is not found in any other field. If we have various types of offers, we can display them in different ways:
  • Offer type [type]: Can not only be CPI but CPE or CPA … send values ​​like cpa, cpe and cpi. In case we want to request offers, in order to have a manager who approves them, add these other fields:
  • Offer status [status]: Can be as simple as a Boolean 0 and 1, or something more elaborated with options like request, pending, approved, or rejected.
  • Request URL [request]: A URL for an automatic request call where the offer ends up as a pending. For example, if the request has been made, can be left empty.

On the other hand, we have an URL to call and parameters we could filter. In the same way, we can give too much or little information. The only mandatory field is a API Key field, a complex unique identifier.

  • API Key [apikey]: Identifier of at least 32 bytes (an alphanumeric could be enough) that identifies you as a user. With this we could have a https URL like this, that would return all your offers: https style: //www.example.com/offers.json apikey = xXxX0123
    Besides, we could include various parameters to filtrate results:
  • Start Point [start]: Page to begin with. For example, 0, 100, 200 …
  • Number of offers to display [limit]: A number of offers, for example, 100.
  • Management of results [order]: With the possibility of ascending or descending, asc or desc according to whether you want the new ones or old first.
  • Offer [OfferId]: Only shows one specific offer.
  • A particular country [country]: Send a country and get one in return.
  • Specific Operative System [device]: A couple of options like iOS or Android. These country and device values ​​could be combined in order to display, for example, only offers for US iPhone or France Android.

To request an offer we can have a URL in which you necessarily pass two parameters: offer and a notice of request.

This way, a call to: https://www.example.com/offers.json?apikey=xXxX0123&offerid=123&request=1 would activate the request to that specific offer. The answer would be the information on that offer.

The JSON result would be something like this:

URL call: https://www.example.com/offers.json?apikey=yYZBq4a7zG9QePusTJNzFZRdvmMEAfkr

  "offerid": 12345,
  "name": "WhatsApp - US - Android - non-incentivated",
  "payout": 0.45,
  "currency": "USD",
  "country": [{
  "device": [{
  "incent": 0,
  "capping_day": 2500,
  "capping_day_left": 2157,
  "capping_month": null,
  "capping_month_left": null,
  "capping_total": null,
  "capping_total_left": null,
  "preview": "https://play.google.com/store/apps/details?id=com.whatsapp",
  "url": "https://www.example.com/tracking/?offerid=12345&publisher=12345",
  "description": null,
  "type": "CPI",
  "status": "request",
  "request": "https://www.example.com/offers.json?apikey=yYZBq4a7zG9QePusTJNzFZRdvmMEAfkr&offerid=12345&request=1"
0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *