Offer Wall API

With the AdGem Offer Wall API, you can implement a fully customized Offer Wall interface that matches your app’s existing design.

To get started, you will need to add your app in the AdGem Publisher Dashboard and obtain your ADGEM_APP_ID.

Next, you will need to call the following API endpoint from your code replacing ADGEM_APP_ID with your unique app id.

https://api.adgem.com/v1/wall/json?playerid=PLAYER_ID&appid=ADGEM_APP_ID

Required Parameters

The Offer Wall API requires the following 2 fields to be sent with your API calls:

Field	Description
`appid`	The unique app ID assigned to your app from the AdGem Publisher Dashboard
`playerid`	The unique ID of the player on your platform

If you’re traffic is originating from in-app and you have access to the GAID or IDFA advertising IDs, then the following fields are also required.

ID	Description
`gaid`	Google Advertising ID, available when the developer is using Google Play Services
`idfa`	Apple Advertising ID, available when the user has not limited ad tracking

Optional Parameters

Parameter	Description
`limit`	Limit the amount of offers returned to a set number
`app_version`	The version of your app where the click originated
`device`	The user’s device type, for example ‘Moto E Plus’
`device_name`	The user’s device name
`ip`	The IP Address for the user who completed the offer
`useragent`	The User Agent from the user’s default browser app
`os_version`	The user’s Operating System version number
`platform`	The platform this user’s device is using, for example ‘ios’
`player_age`	The user’s age as set by the publisher
`player_gender`	The user’s gender as set by the publisher
`player_payer`	A boolean value, as set by the publisher
`player_iap_total_usd`	A integer value, as set by the publisher
`player_created_at`	A datetime stamp without the time zone, as set by the publisher
`player_level`	The level achieved by a player as set by the publisher
`placement`	A integer value that represents the placement of the ad unit as set by the publisher
`c1`	A custom parameter value as set by the publisher
`c2`	A custom parameter value as set by the publisher
`c3`	A custom parameter value as set by the publisher
`c4`	A custom parameter value as set by the publisher
`c5`	A custom parameter value as set by the publisher

By default, the API will attempt to detect the user location and device type by using their IP address and the User Agent.

If the request to the API is being made from your server-side and the not the client, please pass the following 3 parameters with your calls to the API:

Parameters	Description
`ip`	The end-user’s IP address
`useragent`	The end-user’s useragent object.
`platform`	The end user’s device platform type, accepted values: ios, android, or desktop

The API response will always contain the following three objects:

status (success, fail, or error)
wall
offers

The wall object will contain the following data:

Name	Type	Description
id	Integer	The id for this Offer Wall
app_id	String	The unique id for this app
title	String	The title of the Offer Wall
hex	String	The hexadecimal value for the color of the Offer Wall
header_image	String	URL to the image used as the header on the Offer Wall
currency_name_singular	String	Singular name for the virtual currency earned from the Offer Wall
currency_name_plural	String	Plural name for the virtual currency earned from the Offer Wall
currency_image	String	The URL to the image used for the icon representing your virtual currency
multiplier	Integer	The multiplier used when calculating the virtual currency reward amount
offer_filter_setting	String	The offer filter setting as defined from the AdGem Dashboard
category_filter	Array	An array of values representing each offer category you want returned
button_accent_color	String	The hexadecimal value for the button accent colors on the Offer Wall
button_font_color	String	The hexadecimal value for the button font color used on the Offer Wall

The offers object contains an array of the following data:

Name	Type	Description
store_id	String	If the offer is for a mobile app, this is the App Store app ID or Android package name
tracking_type	String	The type of cost for conversion used for the offer, cost-per-action (CPA), cost-per-engagement (CPE) or cost-per-install (CPI)
epc	String	The EPC for this campaign across the network. If the campaign is new and the network EPC has not been calculated the value will return ‘new’
icon	String	The img URL representing the advertiser’s offer, typically an app icon image
name	String	The name of the offer that is shown on the Offer Wall
url	String	The tracking URL to the offer
instructions	String	Any special instructions for the user to complete in order to get their reward
description	String	Description of the offer, typically contains the text creative
short_description	String	Condensed description of the offer’s main conversion event
category_1	String	The primary category that the offer belongs to
category_2	Nullable String	The secondary category that the offer belongs to
amount	Integer	The virtual currency reward amount for the user if the user completes all requirements on the offer
render_sticker	Boolean	Value determining whether offer has a banner, typically utilized to mark special offer. Possible values: “true” or “false” If “true”, the following properties will appear in call
offer_sticker_text_1	String	Text designated to appear in render_sticker #1. Will only appear if render_sticker value “true”
offer_sticker_text_2	Nullable String	Text designated to appear in render_sticker #2. If not using sticker #2, value will be “null”. Will only appear if render_sticker field value “true”
offer_sticker_text_3	Nullable String	Text designated to appear in render_sticker #3. If not using sticker #3, value will be “null”. Will only appear if render_sticker field value “true”
offer_sticker_color_1	String	Hex Color Code for render_sticker #1. Will only appear if render_sticker field value “true”
offer_sticker_color_2	Nullable String	Hex Color Code for render_sticker #2. If not using sticker #2, value will be “null”. Will only appear if render_sticker field value “true”
offer_sticker_color_1	Nullable String	Hex Color Code for render_sticker #3. If not using sticker #3, value will be “null”. Will only appear if render_sticker field value “true”

If your API call is successful, calling the API will return a JSON result like the following example:

  {
    "status": "success",
    "data": [{
        "wall": {
            "id": 1,
            "app_id": "XXXX",
            "title": "Complete Offers To Earn Gems",
            "hex": "551A8B",
            "header_image": null,
            "currency_name_singular": "Gem",
            "currency_name_plural": "Gems",
            "currency_image": "https://adgem-dashboard-production.s3.us-east-2.amazonaws.com/gem.png",
            "multiplier": 100,
            "offer_filter_setting": "all_offers",
            "category_filter": [
                               "app",
                               "trial",
                               "survey",
                               "paid",
                               "free",
                               "user_info_request"
                          ],
                          "button_accent_color": "551A8B",
            "button_font_color": "551A8B"
        },
        "data": [{
            "store_id": null,
            "tracking_type": "CPA",
            "epc": "2.3074",
            "icon": "https://adgem-dashboard-production.s3.us-east-2.amazonaws.com/campaigns/107/campaign-offerwall-creatives/icons/9vBzpAGqNG50g4cyrdIdvcW2WY23DfC6Hej8bxln.jpeg",
            "name": "Hooked on Phonics",
            "url": "https://api.adgem.com/v1/click?appid=XXX&adgem_uid=XXX&cid=XXX",
            "instructions": "Submit VALID information,Sign up for 1 month trial for only $1,Submit payment,Reward revoked if trial is cancelled within 3 days,Redeem your points! *New Users Only",
            "description": "Learning made fun! Sync with your mobile devices! Get a 1 Month Trial for just $1",
            "short_description": "Discover to Earn!",
            "category_1": "trial",
            "category_2": null,
            "amount": 300,
            "render_sticker": true,
            "offer_sticker_text_1": "Top Offer!",
            "offer_sticker_text_2": null,
            "offer_sticker_text_3": null,
            "offer_sticker_color_1": "62B01E",
            "offer_sticker_color_2": null,
            "offer_sticker_color_3": null

        }, {
            "store_id": "com.igg.castleclash",
            "tracking_type": "CPI",
            "epc": "1.4477",
            "icon": "https://adgem-dashboard-production.s3.us-east-2.amazonaws.com/campaigns/165/campaign-offerwall-creatives/icons/201805042008",
            "name": "Castle Clash",
            "url": "https://api.adgem.com/v1/click?appid=281&adgem_uid=e9acb5cbdfb1375869be34b0920c9878&cid=165&playerid=atsl",
            "instructions": "Install and Open the App,Redeem your points!",
            "description": "Build and battle your way to glory in Castle Clash!",
            "short_description": "Build and battle!",
            "category_1": "app",
            "category_2": "free",
            "amount": 78,
            "render_sticker": false
        }]
    }]
  }

Call Examples

PHP

<?php
// Initialize cURL and make the request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.adgem.com/v1/wall/json?appid=ADGEM_APP_ID&playerid=PLAYER_ID');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

// Decode the response into a PHP associative array
$response = json_decode($response, true);

// Make sure that there wasn't a problem decoding the repsonse
if(json_last_error()!==JSON_ERROR_NONE){
    throw new RuntimeException(
        'API response not well-formed (json error code: '.json_last_error().')'
    );
}

// Print out the response details or, any error messages
if(isset($response['status']) && $response['status']==="success"){
    echo 'API call successful';
    echo PHP_EOL;
    echo 'Response Data: <pre>'.print_r($response['data'], true).'';
    echo PHP_EOL;
}else if(isset($response['status']) && $response['status']==="error"){
    echo 'API call error';
    echo PHP_EOL;
    echo 'Errors: <pre>'.print_r($response['data'], true).'';
    echo PHP_EOL;
}else{
    echo 'API call failed';
    echo PHP_EOL;
    echo 'Errors: <pre>'.print_r($response['data'], true).'';
    echo PHP_EOL;
}
?>

Python

  # importing the requests library
  import requests

  # defining the api-endpoint
  API_ENDPOINT = "https://api.adgem.com/v1/wall/json"

  # your Adgem App ID
  ADGEM_APP_ID = "xxxxx"

  # data to be sent to api
  data = {'appid':ADGEM_APP_ID,
          'playerid':'YOUR_PLAYER_ID'}

  # sending post request and saving response as response object
  r = requests.post(url = API_ENDPOINT, data = data)

  # extracting response data
  offerwall_data = r.data
  print(offerwall_data)

Ruby

  require 'net/http'
  require 'json'

  url = 'https://api.adgem.com/v1/wall/json?appid=ADGEM_APP_ID&playerid=PLAYER_ID'
  uri = URI(url)
  response = Net::HTTP.get(uri)
  JSON.parse(response)