AdGem Android SDK

Java native mobile optimized AdGem Android SDK.

This is an extenden version of simplified integration guide here.

PlayStore: https://play.google.com/store/apps/details?id=com.adgem.android.example

Download

Gradle:

implementation 'com.adgem:adgem-android:1.2.0'

Maven:

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

AdGem Android SDK requires at minimum Android 4.1.

Overview

AdGem android SDK is automatically configured by a buld system. To configure SDK specifically for your project:

Add adgem_config.xml to res/xml folder of your project structure:

<adgem-configuration applicationId="ADGEM_APP_ID"
		     standardVideoAdsEnabled="true|false"
		     rewardedVideoAdsEnabled="true|false"
		     offerWallEnabled="true|false" />

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

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

ProGuard

All necessary proguard configurations are automatically supplied by the library. There is no additional configurations needed.

API overview

All communication with SDK can happen via the java AdGem class:

AdGem adgem = AdGem.get();

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

AdGemCallback:

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

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

Once registered, a callback will be used to deliver SDK state change update.

Keep in mind that AdGem will hold a strong reference to a callback. It is caller's responsibility to unregister it. For example, if a callback is being registered in activity's onCreate() then is 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);
        ...
    }
}

Playing videos:

AdGem will download, prepare and cache standard and/or rewarded videos if they are configured via configuration XML:

<adgem-configuration applicationId="ADGEM_APP_ID"
		     standardVideoAdsEnabled="true|false"
		     rewardedVideoAdsEnabled="true|false"
		     offerWallEnabled="true|false" />

Once AdGem has a standard/rewarded video ready to play, it will notify a client via the AdGemCallback:

    AdGemCallback callback = new AdGemCallback() {
        @Override
        public void onStandardVideoAdStateChanged(int newState) {
		// newState will notify a state of a standard video
		// Full list of possible state codes is defined in AdGem class.
        }
        
        @Override
        public void onRewardedVideoAdStateChanged(int newState) {
		// newState will notify a state of a rewarded video
		// Full list of possible state codes is defined in AdGem class.
        }

        @Override
        public void onStandardVideoComplete() {
		// Notifies that the user has finished watching standard video ad.
        }

        @Override
        public void onRewardedVideoComplete() {
		// Reward user for watching a rewarded video ad.
        }
    };

Once video is in ready state (as signaled by a callback), it can be played either via adGem.showStandardVideoAd() or adGem.showRewardedVideoAd() respectively. Video readiness flags are also available via: adGem.isStandardVideoAdReady() and adGem.isRewardedVideoAdReady() fields.

Note that once standard or rewarded video started playing, AdGem will immediately initiate downloading a next one. It is important to monitor changes in a video state since it will transition through multiple states before becoming "ready".

Offer Wall:

AdGem will download and prepare offer wall if it is configured in adgem configuration XML:

<adgem-configuration ...
		     offerWallEnabled="true|false" 
		     ... />

Once AdGem has Offer Wall ready, it will notify subcriber via the AdGemCallback:

    AdGemCallback callback = new AdGemCallback() {
            @Override
            public void onOfferWallStateChanged(int newState) {
		
            }
        
            @Override
            public void onRewardUser(int amount) {
		// Notifies that the user has completed an action and should be rewarded with a specified amount. 
            }
    };

Once Offer Wall is in ready state, it can be displayed by calling adGem.showOfferWall(). Offer Wall readiness flag is available via the adGem.isOfferWallReady() field.

Status codes:

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 session start up
AdGem.STATE_NEEDS_INITIALIZATION	Component needs initialization
AdGem.STATE_NEEDS_CAMPAIGN_REFRESH	On initial launch or after invalidating internal caches
AdGem.STATE_REFRESHING_CAMPAIGN	Checking for active campaign
AdGem.STATE_NEEDS_DOWNLOAD	Will start downloading new media soon
AdGem.STATE_DOWNLOADING	Downloading and caching new ads
AdGem.STATE_READY	A component (video or offer wall) is ready to be displayed

har2008preet/Android-Example