Android SDK Integration

Before You Start

We support Android Operating Systems Version 4.1 (API Level 16) and above. Be sure to:

  • Use Android Studio 3.0 and above

  • Target Android API level 28

  • minSdkVersion level 16 and above

Important! The ADAPTERS for ad networks are modularized as independent .aar files and should be downloaded as required by yourself. If you want to use OpenMediation SDK to mediate networks, Be sure to follow our Add Mediation Networks and Mediation Integration Guides.

 

1. Overview

This Guideline introduces the integration of OpenMediation's SDK in Android Apps.

OpenMediation offers diversified and competent monetization services and supports a variety of Ad formats including Native Ad, Interstitial Ad, Banner Ad, and Rewarded Video Ad. The OpenMediation platform mediates AdTiming, AdMob, Facebook, UnityAds, Vungle, Tapjoy, AppLovin, AdColony, Chartboost, MoPub, Helium, Pangle, TencentAds and ironSource.

New in Version 2.0 !

The OpenMediation SDK equipped with smart ad inventory mechanism and optimized SDK initialization pre-loading mechanism, provides the best mediation solution for app developers. For Rewarded Video, Interstitial and Interactive Ad, the SDK will cache ads automatically and maintain ad inventory regularly, such as pre-loading after initialization, loading after ad served and timing loading etc. You have no need to invoke load() method to cache ads by yourselves anymore. The new APIs are easier to use.
 

 

2. Ads ID

This section introduces how to fetch and use identity information when integrating the OpenMediation SDK, including: APP_KEY, Placement ID, account and configurations of the mediation platform.

APP_KEY: APP_KEY is the sole identification of developer’s application on OpenMediation platform. Developers need to create their Apps and obtain APP_KEY through the OpenMediation Developer Platform.

  • Navigate to Apps -> Select 'App Setting' -> Click on 'App Info'
    android-app-info.png
  • Click on 'Copy' 

Placement ID: identifies the ads placement at OpenMediation. Developers may create multiple ads placement on the OpenMediation Developer Platform to meet their needs. The placement supports formats including BannerAd, InterstitialAd, NativeAd, VideoAd and PromotionAd.

android-om-placement.png

 

3. Add OpenMediation SDK to your Project

Add the following to your project-level build.gradle file.

allprojects {
    repositories {
        google()
        jcenter()
    }
}

Add the following to your application-level build.gradle file inside dependencies section.

dependencies {
    implementation 'com.openmediation:om-android-sdk:2.1.1'
}

 

Cloned GitHub Repository

Alternatively, you can obtain the OpenMediation SDK source and Sample App form the GitHub Repository:

git clone git://github.com/AdTiming/OpenMediation-Android.git

 

4. Update AndroidManifest.xml

Configure your AndroidManifest.xml to add the following permissions into the <manifest> tag but outside the <application> tag.

<!-- Required permissions -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

 

5. Proguard 

You must add the following to your Proguard configuration file (Android Studio: proguard-rules.pro or Eclipse: proguard-project.txt) if you are using Porguard in your application. Failed to do so will lead to errors.

-dontwarn com.openmediation.sdk.**.*
-keep class com.openmediation.sdk.**{*;}

 #R
-keepclassmembers class **.R$* {
   public static <fields>;
}
-keepattributes *Annotation*
-keepattributes InnerClasses
-keepnames class * implements android.os.Parcelable {
   public static final ** CREATOR;
}

 

6. MultiDex

If your project has a multDex operation,Add the following to your build.gradle file.

android {
  buildTypes {
    release {
      multiDexKeepProguard file('multidex-config.pro')
      ...
    }
  }
}

 multidex-config.pro 

-keep class com.openmediation.sdk.**{*;}
-dontwarn com.openmediation.sdk.**.*

 

7. Override Your Activity Lifecycle Methods

Override the onPause()onResume() methods in each of your activities to call the corresponding OpenMediation methods as below:

protected void onResume() {
     super.onResume();
     OmAds.onResume(this);
  } 
protected void onPause() {
     super.onPause();
     OmAds.onPause(this);
  }

 

8. Initialization

Before you can fetch ads from OpenMediation Platform, you should first initialize the OpenMediation SDK when your app started. To do so, we suggest to call OpenMediation SDK's init() method within onCreate() of an Activity as below:

import com.openmediation.sdk.InitConfiguration;
import com.openmediation.sdk.OmAds;
import com.openmediation.sdk.InitCallback;
import com.openmediation.sdk.utils.error.Error;

public class DemoActivity extends Activity {

   @Override
   protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      InitConfiguration configuration = new InitConfiguration.Builder()
                .appKey("Your AppKey")
                .logEnable(false)
                .build();
      OmAds.init(this, configuration, new InitCallback() {

          // Invoked when the initialization is successful.
          @Override
          public void onSuccess() {
          }

          // Invoked when the initialization is failed.
          @Override
          public void onError(Error message) {
          }
      });
    }
}

Note:

  • APP KEY can only be obtained by creating apps on OpenMediation.
  • Activity is the  must-have parameter.  Do not use temporary Activity object as parameter that will due to UnknownException. See Error Code for more information.
  • We suggest that the first call to method loadAd after the app starts should be in the onSuccess callback.
  • No need to invoke loadAd method for Rewarded Video & Interstitial Ads anymore, the SDK will fetch Ads automatic and maintain the ad inventory.
  • The error parameter in onError callback describes the cause of failure. Check the  Error Code for more information and guidance on errors. 

Report Custom Device Identifier

The APP can report the customized device identifier through the SDK, and only needs to call the setCustomDeviceId method to set it before initialization. This identifier will be reflected in user-level data, such as UAR report.

OmAds.setCustomDeviceId(String deviceId);

Best Practice: Init the SDK with AdUnits

The SDK can be  initialized in another way and we recommend this approach as it will only fetch the specific ad units you define in the adUnits parameter. The adUnits parameter is a string array. The following illustrates that the SDK is initiated with Rewarded_Video&Interstitial AdUnits and only these two types Ads will be fetched automatic. 

// Ad Units should be in the type of OmAds.AD_TYPE.AdUnitName, for example:
InitConfiguration configuration = new InitConfiguration.Builder()
    .appKey("Your AppKey")
    .preloadAdTypes(OmAds.AD_TYPE.INTERSTITIAL, OmAds.AD_TYPE.REWARDED_VIDEO)
    .build();
OmAds.init(activity, configuration, callback);

When using this init approach, you can initialize each ad unit separately at different touchpoints in your app flow in one session.

// Init with pre-load Rewarded video ads
InitConfiguration configuration = new InitConfiguration.Builder()
    .appKey("Your AppKey")
    .preloadAdTypes(OmAds.AD_TYPE.REWARDED_VIDEO)
    .build();
OmAds.init(activity, configuration, callback);
// Init with pre-load Interstitial ads
InitConfiguration configuration = new InitConfiguration.Builder()
    .appKey("Your AppKey")
    .preloadAdTypes(OmAds.AD_TYPE.INTERSTITIAL)
    .build();
OmAds.init(activity, configuration, callback);
  • If no parameters are passed in the type, it means that the Rewarded Video and Interstitial ad types will be preloaded by default
  • If you don’t want to do any preloading, please pass in the OmAds.AD_TYPE.NONE parameter
// Init with no pre-load
InitConfiguration configuration = new InitConfiguration.Builder()
    .appKey("Your AppKey")
    .preloadAdTypes(OmAds.AD_TYPE.NONE)
    .build();
OmAds.init(activity, configuration, callback);

Note:

  • AD_Units such as Native and Banner Ad have no need to initiate separately.

 Implement the Callback

The OpenMediation SDK fires several events to inform you of your initialing SDK operation. To receive these events, register to the callback in the init() and implement the onSuccess() and onError() of it.

@Override
public void onSuccess() {
    // Add code here to process init success event.
}
@Override
public void onError(Error error) {
    // Add code here to process init failed event.
    // Parameter message tells the error information.
}

Note:

  • The error parameter in onError callback describes the cause of failure. Check the Error Code for more information and guidance on errors. 

  

Send attribution data to OpenMediation(optional)

If your project also integrates the AppsFlyer SDK, we need you to pass the application attribution data to OpenMediation so that we can help you accurately calculate each Media Source, Campaign level ROAS, and LTV data.

1. When you receive the onConversionDataSuccess callback you can use the sendAFConversionData method for passing the attribution data dictionary:

For apps using AppsFlyer SDK version 5 and above 

@Override
public void onConversionDataSuccess(Map<String, Object> conversionData) {
OmAds.sendAFConversionData(conversionData); }

For apps using AppsFlyer SDK version 4 and below

@Override
public void onInstallConversionDataLoaded(Map<String, String> map) { {
OmAds.sendAFConversionData(map); }

2. When you receive the onAppOpenAttribution callback you can use the sendAFDeepLinkData method for passing the attribution data dictionary:

@Override
public void onAppOpenAttribution(Map<String, String> conversionData) {
OmAds.sendAFDeepLinkData(conversionData); }

 

9. Use the Test Suite to test the integration

  • Add the following dependencies into your apps build.gradle file:
dependencies {
    implementation 'com.openmediation:test-suite:1.1.0'
}
  • Use the following line of code to launch the Mediation Test Suite:
import com.openmediation.testsuite.TestSuite;
...
TestSuite.launch(activity, appKey);

You can get more help through the Test Suite Tool chapter.

 

What’s Next?

1. Integrate our Rewarded Video, Interstitial, Banner, Native and Cross Promotion Ads in your app.
2. Follow 
our Add Mediation Networks and Mediation Network Guides to mediation networks.
3. After completing the above integration work, you can use Test Suite Tool to check whether the SDK aggregation integration is correct

Note: With the OpenMediation SDK, you need to download and add NOT ONLY the SDK of mediation networks you choose to work with BUT ALSO the adapters for those networks.

Was this article helpful?
8 out of 11 found this helpful

Comments

0 comments

Article is closed for comments.