Android SDK Integration Guide

v4.0.3API 28+

Requirements

Before You Begin

Account Requirements:

You have an active AdGem Account
You have added your App to your Account

App Approval:

Your app has been approved in the AdGem system

Important

By default, your app will not have access to AdGem's offers until you complete the initial integration steps and your app is approved. Contact your dedicated Publisher Support Advocate with any questions about the approval process.

:::

Platform Requirements

iOS SDK Requirements

iOS 15.8 or higher
Swift 5 or Objective-C
Xcode 11 or higher

Android SDK Requirements

Android API level 28 (Android 9.0) or higher
Target SDK 34 or higher
Android Studio with Gradle support

Unity SDK Requirements

Unity 2020.3 or higher
iOS or Android build target configured
For iOS: Xcode 11+
For Android: Android Studio with Gradle

Web Offerwall Requirements

Modern web browser with JavaScript enabled
HTTPS-enabled website (recommended for production)
Server-side postback endpoint

Unity Games

Is your Android game built in Unity? We strongly recommend integrating the AdGem Unity SDK for both Android and iOS games built with Unity.

Google Play Services

It is not required, but in order for the SDK to fetch the Google Advertising ID, Google Play Services should be set up within your app. Having the Google Advertising ID available will improve conversion rates and increase your revenue potential.

Integration

Step 0. Create an App Property in the AdGem Publisher Dashboard

Step 0: Create an App Property in AdGem

Before AdGem can populate offers, you need to create an App Property in the AdGem Dashboard.

Create a Publisher Account in the AdGem Publisher Dashboard
Register your App Property in Properties & Apps

Need Help?

Contact your dedicated Publisher Support Advocate if you have any questions about setting up your App Property.

Step 1. Install the AdGem SDK into your Android Project

Gradle Installation

To install via Gradle, add the following to your application's build.gradle:

dependencies {
  implementation 'com.adgem:adgem-android:4.0.3'
}

Maven Installation

Or integrate the Android SDK into your Android Studio Project with Maven by adding the following code to your application's build.maven:

<dependency>
  <groupId>com.adgem</groupId>
  <artifactId>adgem-android</artifactId>
  <version>4.0.3</version>
  <type>pom</type>
</dependency>

Compile Options

In either case, add the following compile options to your application's build.gradle:

compileOptions {
  sourceCompatibility JavaVersion.VERSION_11
  targetCompatibility JavaVersion.VERSION_11
}

R8/ProGuard Configurations

All necessary R8 or ProGuard configurations are automatically supplied by the library. There are no additional configurations needed.

Step 2. Configure the AdGem SDK

Create a new XML resource file called adgem_config.xml within the res/xml resource directory. If the xml directory does not exist, please create it.

Once you have created the adgem_config.xml file, paste in the following code:

<adgem-configuration
    applicationId="ADGEM_APP_ID"
    offerwallEnabled="true|false"
    lockOrientation="true|false"/>

Update the XML in adgem_config.xml replacing ADGEM_APP_ID with your actual AdGem App ID defined in the AdGem Publisher Dashboard > Properties & Apps.

Next, update the offerwallEnabled boolean value in the adgem_config.xml. By default, it is set to false.

Optionally, you may also lock the orientation of the ads by setting lockOrientation to true (by default it is set to false).

Add the following tag to the <application> in the AndroidManifest.xml:

<meta-data android:name="com.adgem.Config"
    android:resource="@xml/adgem_config"/>

Step 3. Use the AdGem Class

All communication with the SDK happens via the AdGem class. Within your application's main or first Activity class, add the following line of code:

AdGem adgem = AdGem.get();

note

There is no need to store an instance of AdGem globally. The SDK will cache its instance on the first call and will always return the same one for all subsequent calls to AdGem.get().

Use the AdGem class to show the Offer Wall in your project:

adGem.showOfferwall(); // Show Offer Wall

Step 4. Register the AdGem Offer Wall Callback

The AdGem SDK provides callbacks that notify when offer wall internal state changes.

OfferwallCallback callback = new OfferwallCallback() {
    @Override
    public void onOfferwallLoadingStarted() {
        // Notifies that the offer wall loading has started.
    }

    @Override
    public void onOfferwallLoadingFinished() {
        // Notifies that the offer wall has been loaded.
    }

    @Override
    public void onOfferwallLoadingFailed(String error) {
        // Notifies that the offer wall has failed to load.
    }

    @Override
    public void onOfferwallRewardReceived(int amount) {
        // Notifies that the user has completed an action and should be rewarded with a specified virtual currency amount.
    }

    @Override
    public void onOfferwallClosed() {
        // Notifies that the offer wall was closed.
    }
};

Offer wall callback may be registered through the instance of AdGem:

AdGem adgem = AdGem.get();
adgem.registerOfferwallCallback(callback);

Once registered, a callback will be used to deliver offer wall updates.

Important

AdGem will hold a strong reference to a callback. It is the caller's responsibility to unregister it. For example, if a callback is being registered in activity's onCreate() then it must be unregistered in the corresponding onDestroy() call.

public class GameActivity extends AppCompatActivity {
    private AdGem adGem;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        ...
        adGem = AdGem.get();
        adGem.registerOfferwallCallback(callback);
        ...
    }

    @Override
    protected void onDestroy() {
        ...
        adGem.unregisterOfferwallCallback(callback);
        ...
    }
}

Offer Wall can be displayed by calling adGem.showOfferwall(activity).

Step 5. Set the Player ID

Setting the Player ID

IMPORTANT: The Player ID is Required

The player_id parameter must be set with a unique identifier for each user in your application. This identifies the player so that virtual currency can be attributed to their account via the postback request. The player ID must remain constant for each unique player to:

Prevent players from completing an offer more than once
Ensure players receive their rewards correctly

Missing Player ID

Tracking URL clicks that do not contain a player_id value will be redirected to a 404 error page.

Player ID Structure Requirements

Requirement	Details
Case	Letters must be lowercase
Characters	Alphanumeric characters, hyphens, and underscores only
Max Length	256 characters
Forbidden	Emojis, special characters, uppercase letters

Good Examples:

abc-123-efg-456
user_12345
player-a1b2c3d4

Bad Examples:

aBc-123-Efg-456 (contains uppercase)
player@123! (contains special characters)
user-😀 (contains emoji)

PlayerMetadata player = PlayerMetadata.Builder.createWithPlayerId("myPlayerId")
  .age(23)
  .iapTotalUsd(10)
  .level(4)
  .placement(2)
  .isPayer(true)
  .gender(PlayerMetadata.Gender.FEMALE)
  .createdAt("2018-11-16 06:23:19.07")
  .customField1("custom_field_1")
  .customField2("custom_field_2")
  .customField3("custom_field_3")
  .customField4("custom_field_4")
  .customField5("custom_field_5")
  .build();

adgem.setPlayerMetaData(player);

Additional Information

Example App

For an example integration, please take a look at the sample app source code available on GitHub and a working sample app on Google Play.

Optional Parameters

note

All parameter names and their values are case-sensitive.

The AdGem Android SDK allows for several optional parameter values to be stored such as age, gender, etc. These values can then be retrieved again on each conversion postback and used to segment your audiences and optimize your mobile ad revenue earnings. Please visit the Optional Parameters to learn more.

Postback Setup

If you have opted for a "Server Postback", on each successful offer completion by a user AdGem will send a GET request to your server. Please visit our guide on Server Postback Setup to learn more.

ProGuard Configuration

If your code reads proguardFiles getDefaultProguardFile('proguard-android-optimize') in place, please change the code to getDefaultProguardFile('proguard-android.txt') instead. This will ensure that your App will be able to launch with the AdGem SDK enabled.

Updated on May 19, 2025

Requirements​

Platform Requirements​

Integration​

Step 0. Create an App Property in the AdGem Publisher Dashboard​

Step 0: Create an App Property in AdGem​

Step 1. Install the AdGem SDK into your Android Project​

Gradle Installation​

Maven Installation​

Compile Options​

R8/ProGuard Configurations​

Step 2. Configure the AdGem SDK​

Step 3. Use the AdGem Class​

Step 4. Register the AdGem Offer Wall Callback​

Step 5. Set the Player ID​

Player ID Structure Requirements​

Additional Information​

Example App​

Optional Parameters​

Postback Setup​