Android SDK Integration Guide

v5.0.0API 23+

Upgrading from v4?

Version 5.0.0 changes how the SDK is initialized and how the player is set. See the Android SDK v4 → v5 migration guide for a step-by-step upgrade path.

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

Android SDK Requirements

• Android API level 23 (Android 6.0) or higher
• Target SDK 34 or higher
• Android Studio with Gradle support

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.

Deterministic attribution

The Google Advertising ID lets advertisers match an install back to the click deterministically by device ID (when the user hasn't limited ad tracking) — the most reliable form of attribution. The SDK collects the GAID and forwards it automatically, so no extra work is required on your side. Without it, attribution falls back to fingerprint matching, which is far less reliable.

---

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.

1. Create a Publisher Account in the AdGem Publisher Dashboard
2. 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:5.0.0'
}

Maven Installation

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

<dependency>
<groupId>com.adgem</groupId>
<artifactId>adgem-android</artifactId>
<version>5.0.0</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. Initialize the AdGem SDK

All communication with the SDK happens via the AdGem class. Initialize the SDK in your Application class's onCreate() method by passing your AdGem App ID through AdGemConfig.Builder:

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        AdGem.get().initialize(this, new AdGemConfig.Builder("ADGEM_APP_ID").build());
    }
}

Replace ADGEM_APP_ID with your actual AdGem App ID from the AdGem Publisher Dashboard > Properties & Apps.

initialize() is non-blocking — all disk and network probes run on a background thread. It is safe to call from any thread. Calling initialize() again with the same AdGemConfig is a no-op; calling it with a different App ID tears down the previous runtime and brings up a fresh one. The previously set player metadata is cleared on re-initialization and must be supplied again.

When you need to fully tear the SDK down (for example on user logout, A/B variant change, or in tests), call:

AdGem.get().close();

close() returns immediately; teardown of in-flight network calls and integrations happens on the main looper.

note

There is no need to store an instance of AdGem globally. The SDK caches its singleton; every call to AdGem.get() returns the same instance.

Step 3. Identify the Player

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)

The player ID is required at the time you construct PlayerMetadata — pass it directly to the Builder constructor. Optional attributes (age, gender, level, custom fields, etc.) are added via the builder and may be supplied or omitted as needed:

Date playerCreatedAt = ...; // when the player account was created on your system

PlayerMetadata player = new PlayerMetadata.Builder("myPlayerId")
  .age(23)
  .iapTotalUsd(10)
  .level(4)
  .placement(2)
  .isPayer(true)
  .gender(PlayerMetadata.Gender.FEMALE)
  .createdAt(playerCreatedAt) // java.util.Date, serialized as "yyyy-MM-dd HH:mm:ss" in UTC
  .customField1("custom_field_1")
  .customField2("custom_field_2")
  .customField3("custom_field_3")
  .customField4("custom_field_4")
  .customField5("custom_field_5")
  .build();

AdGem.get().setPlayer(player);

setPlayer() is safe to call from any thread and may be called immediately after initialize(). The SDK guarantees that the player metadata is applied before the Offerwall opens. Calling setPlayer() with a different player ID cancels any in-flight requests and regenerates the SDK's internal salt so that subsequent traffic cannot be correlated to the previous identity.

Step 4. Register the AdGem Offerwall Callback

The AdGem SDK provides callbacks that notify when Offerwall internal state changes. Failures are surfaced through a typed AdGemError — inspect error.getKind() for programmatic handling:

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

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

    @Override
    public void onOfferwallLoadingFailed(AdGemError error) {
        // Notifies that the Offerwall has failed to load.
        // error.getKind() is one of:
        //   NOT_INITIALIZED       — initialize() was not called or close() was called
        //   NOT_READY             — initialization in progress, or setPlayer() has not been called
        //   OFFERWALL_UNAVAILABLE — the Offerwall failed to load from the server (including network failures)
        //   INTERNAL              — unexpected failure; error.getCause() carries the throwable
    }

    @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 Offerwall was closed.
    }
};

Register the callback through the AdGem instance. Registration and unregistration must happen on the main thread:

AdGem.get().registerOfferwallCallback(callback);

Once registered, the callback receives Offerwall updates on the main thread.

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 an activity's onCreate() then it must be unregistered in the corresponding onDestroy() call.

public class GameActivity extends AppCompatActivity {
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        ...
        AdGem.get().registerOfferwallCallback(callback);
        ...
    }

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

Step 5. Show the Offerwall

Display the Offerwall by calling showOfferwall() with an activity context:

AdGem.get().showOfferwall(activity);

If the SDK has not yet finished initializing or if setPlayer() has not been called, showOfferwall() immediately delivers an AdGemError (NOT_INITIALIZED or NOT_READY) to all registered callbacks rather than failing silently — make sure your callback is registered before invoking showOfferwall().

---

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. Passing PlayerMetadata.Gender.UNKNOWN omits the gender parameter entirely.

Postback Setup

If you have opted for a "Server Postback", on each successful offer completion by a user AdGem will send a server postback to your server. See Postbacks 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.