Android Integration Documentation
1. API Key
Register your app on the appmediation platform for obtaining the API key
2. Android Demo App
Download appmediation demo application with all the new features and integration from here.
3. Integration Setup
3.1 Prerequisites
- Use Android Studio 1.0 or higher
- Target Android API level 16 or higher
- Compile SDK version 24 or higher, for lower versions please contact support.
3.2 Gradle Integration
To add appmediation to your project you need to follow this simple steps:
- Include play-services-ads and appcompat-v7 library in your project
dependencies {
compile 'com.android.support:appcompat-v7:26.1.0'
compile 'com.android.support:recyclerview-v7:26.1.0'
compile 'com.google.android.gms:play-services-ads:15.0.1'
}
- Update android packaging options like in example below
android {
....
packagingOptions {
pickFirst 'publicsuffixes.gz'
}
}
- Download this archive and add all libraries from it to your project. You can read how to do that here.
3.3 Enable Multidex
Our SDK contains many ad networks to provide best performance metrics. You can see a full list in chapter 5. Third-Party Integration Versions. Because of many libraries that we are using your app might encounter 65K methods limit. To prevent this issue from happening we recommend to enable Multidex. You can read how to do it here: Enable Multidex for Apps with Over 64K Methods
3.4 Manifest setup
You need to define some providers and receivers so that our partners could work properly. Here is an example with bold lines being the parts that you need to add to your AndroidManifest.xml file:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.appmediation.testapp">
<application
android:name=".ExampleApplication"
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:theme="@style/AppTheme">
<activity
android:name=".MainActivity"
android:label="@string/app_name">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<!-- appmediation and partners -->
<!-- StatApp -->
<receiver android:name="com.startapp.android.publish.common.metaData.BootCompleteListener" >
<intent-filter>
<action android:name="android.intent.action.BOOT_COMPLETED" />
</intent-filter>
</receiver>
<!-- Ogury -->
<receiver android:name="io.presage.receiver.NetworkChangeReceiver">
<intent-filter>
<action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
<action android:name="android.net.wifi.WIFI_STATE_CHANGED" />
<action android:name="io.presage.receiver.NetworkChangeReceiver.ONDESTROY" />
</intent-filter>
</receiver>
<receiver android:name="io.presage.receiver.AlarmReceiver" />
<provider
android:name="io.presage.provider.PresageProvider"
android:authorities="${applicationId}.PresageProvider"
android:enabled="true"
android:exported="true" />
</application>
</manifest>
Note: If you are using AdMob version 17.0.0 or higher then you are required to specify a <meta-data> tag with key com.google.android.gms.ads.APPLICATION_ID in your AndroidManifest.xml. For more details contact your Partner Manager. Example:
<manifest>
<application>
<meta-data
android:name="com.google.android.gms.ads.APPLICATION_ID"
android:value="ADMOB_APP_ID"/>
</application>
</manifest>
3.5 GDPR (EU & EEA Users Only)
You need to obtain end-users consent from EU & EEA users before using our services. And we have developed three ways to help you do that. Refer to options below:
3.5.1 Smart Consent
By default, this feature is enabled and if you want to disable it you would have to call ‘showConsentAutomatically(false)’ before displaying any ads. This feature checks requests’ country of origin and then displays a consent window before the first ad if its required.
3.5.2 Consent Window
You can display appmediation consent window any time you would like. Each time when you are required to collect end-user data consent you can call Consent Window. To check if SDK already had response saved you can use ‘wasConsentSet()’ method. Here is an example:
if (!AMSDK.wasConsentSet(activity)) {
AMSDK.showGdprNotice(activity, new GdprDialogListener() {
@Override
public void onOptionSelected(boolean gdprConsent) {
// user has selected an option to agree or to disagree
}
@Override
public void onCancelled() {
// window was canceled
}
});
}
Note: You can also use this method without setting any listeners: AMSDK.showGdprNotice(activity, null)
Note: You don’t have to use AMSDK.setGdprConsent() in onOptionSelected, it will be called automatically.
3.5.3 Consent Function
Call this function to set user consent preferences and it is highly suggested to set this method before initializing Appmediation SDK, otherwise, the SDK will initialize with default false which can lead to non-personalised ads.
AMSDK.setGdprConsent(activity, userConsent);
Possible values for ‘userConsent’ above are: AMSDK.GdprConsent.AGREE, AMSDK.GdprConsent.DISAGREE, AMSDK.GdprConsent.NOT_REQUIRED, AMSDK.GdprConsent.UNKNOWN
3.6 SDK Initialisation
Before loading ads, initialize the appmediation SDK by calling AMSDK.init() with your app key. We strongly recommend doing this for every activity that is using appmediation ads on ‘onCreate’ method. Also, note that your app key and package name should match to those that are mentioned in your app settings in appmediation pannel.
Here’s an example of the appmediation SDK initialization. You need to add only highlighted part to your ‘onCreate’ method.
public class ExampleActivity extends Activity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
AMSDK.init(this, "YOUR_APP_KEY");
}
}
3.7 Interstitial Ads
Interstitial ads are full-screen ads that cover the interface of the host application. They can be full screen static interstitial ads or video ads.
3.7.1 Basic
To display interstitial ads you just need to call this single line of code:
AMInterstitial.show(activity);
3.7.2 Advanced
3.7.2.1 Delegates
If you would like to have more control over the interstitial then you can set up interstitial listener before requesting ads:
AMInterstitial.setListener(new AMListener() { @Override public void onLoaded() { Log.d("Interstitial ad", "onLoaded"); }@Override public void onFailed(AMError error) { Log.d("Interstitial ad", "onFailed: " + error.name()); } @Override public void onShowed() { Log.d("Interstitial ad", "onShowed"); } @Override public void onClosed() { Log.d("Interstitial ad", "onClosed"); } @Override public void onClicked() { Log.d("Interstitial ad", "onClicked"); } });
3.7.2.2 Manual pre-loading
By default, SDK prepares next interstitial ad so that you would always have something to display and in case you want to control manually when interstitial is pre-loaded then you can set AutoLoad off and use AMInterstitial.load(Activity) to start pre-loading. When it is ready you will receive a callback in AMListener if you set it up or you could use AMInterstitial.isReady() to check it manually. After the interstitial ad is pre-loaded you can use AMInterstitial.show(Activity) to display it.
P.S: Only one interstitial ad can be pre-loaded at a time.
3.8 Rewarded Video
Rewarded video ads are full-screen video ads that users have the option of watching in full in exchange for in-app rewards.
3.8.1 Basic
To display rewarded video ads you just need to call this single line of code:
AMRewardedVideo.show(activity);
3.8.2 Advanced
3.8.2.1 Delegates
If you would like to have more control over your rewarded video ads then you can set up rewarded video listeners before requesting ads:
AMRewardedVideo.setListener(new AMRewardedListener() {
@Override
public void onLoaded(String currency, String amount) {
String rewardInfo = amount + " " + currency;
Log.d("Rewarded ad", "onLoaded: " + rewardInfo);
}
@Override
public void onCompleted(String currency, String amount) {
String rewardInfo = amount + " " + currency;
Log.d("Rewarded ad", "onCompleted: " + rewardInfo);
}
@Override
public void onFailed(AMError error) {
Log.d("Rewarded ad", "onFailed: " + error.name());
}
@Override
public void onShowed() {
Log.d("Rewarded ad", "onShowed");
}
@Override
public void onClosed() {
Log.d("Rewarded ad", "onClosed");
}
@Override
public void onClicked() {
Log.d("Rewarded ad", "onClicked");
}
});
3.8.2.2 Manual pre-loading
By default, SDK prepares next rewarded video ad so that you would always have something to display and in case you want to control manually when interstitial is pre-loaded then you can set AutoLoad off and use AMRewardedVideo.load(Activity) to start pre-loading. When it is ready you will receive a callback in AMRewardedListener if you set it up or you could use AMRewardedVideo.isReady() to check it manually. After the rewarded video ad is pre-loaded you can use AMRewardedVideo.show(Activity) to display it.
P.S: Only one rewarded video ad can be pre-loaded at a time.
3.8.3 Credit Reward
3.8.3.1 Client Side (SDK Callback)
When user has watched video completely then use “onCompleted” callback to reward user.
@Override
public void onCompleted(String currency, String amount) {
Log.d("Rewarded ad", "onCompleted: " + amount + " " + currency);
}
3.8.3.2 Server Side (S2S Callback)
We also support server-side reward callbacks to securely pass reward data. Server-to-server callbacks are sent to your server when a user has watched an ad. You can use these callbacks to reward players with virtual goods and to e.g. detect and prevent cheating.
By default it is not enabled and you can enable them by following steps from here.
To use S2S Callback feature, you must set user ID by using AMSDK.setUserIdentifier(“User#123”) method before SDK initialisation
3.9 Banner Ads
Banner ads are rectangular image or text ads that occupy a spot within an app’s layout. They stay on the screen while users are interacting with the app, and can refresh automatically after a certain period of time.
3.9.1 Basic
To display banner ads you just need to call one line of code.
AMBanner.show(activity, Gravity.BOTTOM); // or you could use Gravity.TOP
3.9.2 Advanced
3.9.2.1 Delegates
If you would like to have more control over banner ads then you can set up banner listeners before requesting ads:
AMBanner.setListener(new AMBannerListener() {
@Override
public void onLoaded() {
Log.d("Banner ad", "onLoaded");
}
@Override
public void onFailed(AMError error) {
Log.d("Banner ad", "onFailed: " + error.name());
}
@Override
public void onShowed() {
Log.d("Banner ad", "onShowed");
}
@Override
public void onClicked() {
Log.d("Banner ad", "onClicked");
}
});
3.9.2.2 Custom position
If you would like to have more control over where the banner is displayed you can add any view container to your layout (view container should extend ViewGroup) and give it a unique ID. Then you can use AMBanner.showInView(Activity, viewId) to display appmediation banner in that view
3.9.2.3 Auto-refresh
By default banners are automatically refreshed every 20 seconds. But if you would like to disable auto refresh you can turn it off by using AMBanner.setAutoRefresh(false).
3.9.2.4 Banner Sizes
A banner can be set up to have one of the following size options:
| Option | Size (dp) |
| STANDARD | 320x50 |
| LARGE | 728x90 |
| FULL_WIDTH | Dynamic* |
*Dynamic – banner width will be the same as the screen width. Banner height will be 50dp for handphones and 90dp for tablets
By default size is set to FULL_WIDTH, but you can change this by adding enum AMBannerSize as a parameter to AMBanner.show. Here is an example:
AMBanner.show(BannerActivity.this, AMBannerSize.STANDARD, Gravity.TOP);
4. Advanced Features
4.1 Test Mode
It provides the functionality to display test ads for integration testing and 100% fill. You should set test mode before initializing the SDK.
AMSDK.setTestMode(true);
4.2 Auto Load
Auto load feature is on by default to make integration simpler. For interstitial and rewarded video it: 1) Prepares next ad right after SDK is initialized 2) Prepares next ad when the previous ad has been shown For banner, it loads new banner every 20 seconds
You can disable this feature by calling AMSDK.setAutoLoad(false) function and it will be disabled for all ad formats. It is also recommended to call this before initializing SDK.
4.3 Error codes
All ad formats support error reporting. Errors will be returned on onFailed(AMError error) if corresponding ad listener is set up. Overall you can stumble upon this errors:
@Override
public void onFailed(AMError error) {
Log.d("Banner ad", "onFailed: " + error.name());
switch (error) {
case NO_ADS:
// we have no ads to serve or this zone is not set up correctly.
// if you receive this error it is best to contact [email protected] or your account manager
break;
case COMUNICATION_ERROR:
// SDK was not able to get a response from appmediation server.
// possible solution - check internet connection
break;
case NOT_INIT:
// you forgot to initialize SDK or there was error initializing.
// possible solution - check that your package id and app key should be same as registered in publisher panel
break;
case INTERNAL_ERROR:
// you shouldn't be able to receive this error, but if you did receive it - please contact [email protected] or your account manager
break;
}
}
5. Third-Party Integration Versions
| Network Name | Version | Supported AMSDK version |
| Unity | 2.2.1 | ≥1.0.0 |
| Tapjoy | 11.12.0 | ≥1.0.0 |
| Applovin | 8.0.0 | ≥1.0.0 |
| Inmobi | 7.2.1 | ≥1.0.0 |
| Mobvista | 8.11.2 | ≥1.0.0 |
| StartApp | 3.8.4 | ≥1.0.0 |
| Chartboost | 7.2.0 | ≥1.2.0 |
| Vungle | 6.2.5 | ≥1.3.0 |
| AdMob | – | ≥1.4.0 |
| Ogury | 2.2.12 | ≥1.5.0 |
| AdColony | 3.3.3 | ≥1.6.0 |
| 4.28.1 | ≥1.8.0 | |
| MyTarget | 5.1.2 | ≥1.10.0 |