Skip to content

Offer Wall API Integration


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


Requirements

Before you Begin


Related Readings

For a complete picture of the Static API Integration with your property, be sure to read these articles


Step 1 - Update API

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

Step 2 - Update Tracking Source

If your traffic source is originating from in-app then continue with In-App Traffic or if the request to the API is being made from your server-side and the not the client then continue with Server Side Request.

Traffic Sources

If your 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

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

Additional Parameters

Parameter Required Description
limit Optional Limit the amount of offers returned to a set number
app_version Recommended The version of your app where the click originated
device Recommended The user’s device type, for example ‘Moto E Plus’
device_name Recommended The user’s device name
os_version Recommended The user’s Operating System version number
player_age Optional The user’s age as set by the publisher
player_gender Optional The user’s gender as set by the publisher
player_payer Optional A boolean value, as set by the publisher
player_iap_total_usd Optional A integer value, as set by the publisher
player_created_at Optional A datetime stamp without the time zone, as set by the publisher
player_level Optional The level achieved by a player as set by the publisher
placement Optional A integer value that represents the placement of the ad unit as set by the publisher
c1 Optional A custom parameter value as set by the publisher
c2 Optional A custom parameter value as set by the publisher
c3 Optional A custom parameter value as set by the publisher
c4 Optional A custom parameter value as set by the publisher
c5 Optional A custom parameter value as set by the publisher


Once you've completed creating the request, please proceed to the API Response.

If the request to the API is being made from your server-side and the not the client then you are required to send us the following parameters with your calls to the API: ip, useragent, and platform.

The following table shows the supported values you send to us with your calls to the API.

Parameters

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


Once you've completed creating the request, please proceed to the API Response.


Step 3 - Test API Response

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”

Successful API Call

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
// 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&ip=IP&useragent=USER_AGENT&platform=PLATFORM');
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;
}
?>
  # 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,
          'ip': YOUR_PLAYER_IP,
          'useragent': YOUR_PLAYER_USERAGENT,
          'platform': YOUR_PLAYER_PLATFORM}

  # 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)
  require 'net/http'
  require 'json'

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

Back to top