Skip to content

Android SDK Integration Guide

Beta

Joining the Beta

AdGem's Andoid SDK package is currently in a beta status. If you would like to join the beta program and utilize this integration type, please feel free to provide your Integration Specialist with feedback. If you do not wish to use the Beta Android SDK package, you can use our full web offerwall integration to create a similar user experience.

Requirements

Before you Begin

  • You must have an active AdGem Account
  • You must add your App to your Account
  • Is your Android game built in Unity? We strongly recommend integrating the AdGem Unity SDK for both Android and iOS games built with Unity.
  • Please note the AdGem SDK requires Android 9.0 OS or higher.
  • It is not required, but in order for the SDK to fetch the Google Advertising Id, Google Play Services should be setup within your app. Having the Google Advertising Id available, will improve conversion rates and increase your revenue potential.
  • In order for your app to have access to AdGem's offers, you will need to ensure your app is approved in the AdGem system. Please reach out to your dedicated Publisher Support Advocate with any questions.

Integration

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.1'
}

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.1</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

  1. 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 replacing any boilerplate code added by Android Studio:

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

Screenshot

  1. 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.


  1. Add the following tag to the 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();

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

Use the AdGem class to show various ad types 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.

Keep in mind that 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 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 (the unique identifier for a user)

For increased fraud protection, we require you set the playerId (a unique id for your user) parameter. 

PlayerMetadata player = new 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

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.

Tip

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 September 11, 2024