Skip to content

Android SDK Integration Guide

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.

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:3.3.0'
}

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>3.3.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. 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"
            interstitialAdsEnabled="false"
            rewardedVideoAdsEnabled="false"
            offerWallEnabled="true|false"
            lockOrientation="true|false"/>

Screenshot
2. 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 following boolean values interstitialAdsEnabled, rewardedAdsEnabled, offerWallEnabled in the adgem_config.xml for the ad formats you plan to use within your application. By default, they are all set to true.

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


Step 3. Add the following tag to the in the AndroidManifest.xml

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


Step 4. Initializing 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 5. Register the AdGem Callback

The AdGem SDK offers callbacks that notify when its internal state changes.

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

Once the callback is registered, it will be used to deliver SDK state change 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.registerCallback(callback);
        ...
    }

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

Offer Wall Callbacks

AdGem will download and prepare the offer wall if it is configured in the adgem_config.xml configuration file:

<adgem-configuration applicationId="**ADGEM_APP_ID**"
...
offerWallEnabled="true" />

Once AdGem has the Offer Wall ready, it will notify the subscriber via the OfferWallCallback:

OfferWallCallback callback = new OfferWallCallback() {
    @Override
    public void onOfferWallStateChanged(int newState) {
        // Notifies offer wall state change
    }

    @Override
    public void onOfferWallReward(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. Once Offer Wall is in ready state, it can be displayed by calling adGem.showOfferWall(activity). Offer Wall readiness flag is available via the adGem.isOfferWallReady() field.

Status Codes The same status codes will be used to notify about state of a standard, rewarded video or offer wall.

Constant Value Description
AdGem.STATE_ERROR Identifies that internal error ocurred. AdGem will retry download automatically. Exact error is immediately available via adGem.getError()
AdGem.STATE_DISABLED A component is disabled in configuration xml
AdGem.STATE_INITIALIZING AdGem is initializing this component now. Usually hapenns on a session start up
AdGem.STATE_NEEDS_INITIALIZATION AdGem is marked a component as the one that needs initialization
AdGem.STATE_NEEDS_CAMPAIGN_REFRESH Usually happens on initial lauunch or after invalidating internal caches
AdGem.STATE_REFRESHING_CAMPAIGN AdGem is checking for active campaign
AdGem.STATE_NEEDS_DOWNLOAD AdGem has identified that campaign was no longer valid and will start downloading new media soon
AdGem.STATE_DOWNLOADING AdGem is downloading and caching new ads
AdGem.STATE_READY A component (video or offer wall) is ready to be displayed


Step 6. Set the player id (for non games, the unique identifier for a user)

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

PlayerMetadata player = new PlayerMetadata.Builder()
  .id("abc123")
  .age(23)
  .iapTotalUsd(10)
  .level(4)
  .placement(2)
  .isPayer(true)
  .gender(PlayerMetadata.Gender.FEMALE)
  .createdAt("2018-11-16 06:23:19.07")
  .customFields("custom item 1", "custom item 2", "custom item 3", "custom item 4", "custom item 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, player ID, 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 July 13, 2023

Back to top