Offer Wall API Integration

---

Why the Offer Wall API?

The Offer Wall API allows Publishers to implement a fully customized Offer Wall interface that matches their app’s existing design. This integration type can be used in a variety of UIs and works especially well for “Featured Placement” sections.

The Offer Wall API leverages AdGem’s EPC sorting and GEO targeting algorithms to help optimize monetization for Publishers, limiting complex development work. Publishers can limit the number of results returned in the Offer Wall API call, resulting in a faster and less resource heavy call.

We recommend you call our every 5 minutes to ensure your players have access to the most up to date offers.

---

Limitations

Some features of the web integrated AdGem Offer Wall are not currently accessible via the Offer Wall API.

These include:

• The AdGem Reward Status model which allows Players to view their In-Progress and Completed offers

** Please keep this in mind prior to implementation. **

---

Requirements

Before you Begin

• Must have an active AdGem account
• Must have an property to your account

---

Related Readings

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

• Essentials Overview
• Offerwall Promotions

---

Step 1 - Update API

Please contact your AdGem Publisher Support Advocate to receive the API endpoint for the Offer Wall API.

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

Optional Parameters

The Offer Wall API allows the following to be sent with your API calls to allow futher campaign filtering:

Parameter	Type	Description
tracking_types	string	Optionally, you can filter the response to contain only certain tracking types. The API will accept the following category values: CPI, CPE, CPA, Survey & CPC. Please note that all values are case sensitive. These values can be combined in the call to select multiple tracking types. Example: tracking_types=CPI,Survey

Native Offer Presentation Tip

Using the disclaimer field for Native Offers
• We highly recommend that publishers ensure that all information included in the disclaimer field is made visible to users interacting with offers. AdGem Player Support will enforce offer attribution windows as set by our advertisers, making it important that your users are aware of this completion window prior to offer engagement.

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

In-App TrafficServer Side Request

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
completion_difficulty	Integer	Indicates the level of difficulty in completing an offer. The possible values are 1 (easy), 2 (medium) and 3 (hard). It takes into account factors such as complexity and duration of the offer.
OS	array	Indicates the operating system for which the campaign is available.
OS.android	boolean	true/false
OS.ios	boolean	true / false
OS.web	boolean	true / false
OS.min_ios	string	10.1
OS.max_ios	string	11
OS.min_android	string	4
OS.max_android	string	8.0
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,
            "completion_difficulty": 1,
            "OS": {
              "android": false,
              "ios": true,
              "web": false,
              "min_ios": "14.0",
              "max_ios": null,
              "min_android": null,
              "max_android": null
              },
            "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,
            "completion_difficulty": 1,
            "OS": {
              "android": true,
              "ios": false,
              "web": false,
              "min_ios": null,
              "max_ios": null,
              "min_android": null,
              "max_android": null
            },
        }]
    }]
  }

---

Call Examples

PHPPythonRuby

<?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)

---