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
// 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;
}
?>
# 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)
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)