Android Setup¶

This guide is intended for publishers who want to monetize an Android app with ADvantage. Integrating the ADvantage SDK into an app is the first step toward displaying ads and earning revenue. Once that's done, you can proceed to implement one or more of the supported ad formats.

Ad Spaces

Before you start integrating ADvantage into your project you should plan together with your client/sales team the exact positions and behaviour of each ad space inside of your app (e.g. which ad format you want to display). After that you must prepare the app to be able to show the ad spaces.

Info

Add these ProGuard rules to your file if you are using minifyEnabled=true.

-keepattributes JavascriptInterface
-keepclassmembers class ** {
    @android.webkit.JavascriptInterface <methods>;
}
-keep class com.digitalsunray.advantage.CoreJSBridge {public *;}
-keep class com.digitalsunray.advantage.AdvantagePluginJSBridge {public *;}
-keep class com.digitalsunray.advantage.MraidPluginJSBridge {public *;}
-keep class com.digitalsunray.advantage.Advantage {public *;}
-keep public enum com.digitalsunray.advantage.Advantage$** {public *;}
-keep public interface com.digitalsunray.advantage.Advantage$** {public *;}
-keep class com.digitalsunray.advantage.EventHandler {public *;}
-keep public enum com.digitalsunray.advantage.util.Enum$** {public *;}
-keep public enum com.digitalsunray.advantage.PermittedAndSupportedFeatures** {public *;}
-keep class com.digitalsunray.advantage.util.Log {public *;}
-keep class com.digitalsunray.advantage.models.** {public *;}

Prerequisites¶

Android Studio 3.0 or higher
Target Android API level 21 (5.0 Lollipop or higher)
Google Play services (Google Ad Service)
Valid license for the ADvantage SDK

Update your AndroidManifest.xml¶

Google Ads SDK

Starting on Google Ads SDK v17.0.0, it is a requirement to have an AdMob app ID. Older versions does not need to add this meta-data.

<manifest>
    <application>
        <!-- TODO: Replace with your real AdMob app ID -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-################~##########"/>
    </application>
</manifest>

Import the ADvantage SDK¶

Gradle¶

Make sure your project-level build.gradle includes our Maven repository:

allprojects {
    repositories {
        ...
        maven { 
            url("https://maven.digitalsunray.com/") 
        }
    }
}

Add ADvantage SDK dependencies to the app-level build.gradle and ensure that the project supports Java 8.

android {
   ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    ...
    implementation 'com.digitalsunray:advantage:2.6.3.0'
}

Import Manually¶

Download the latest version of the SDK from the Download Section
Extract the ZIP file
Import AAR file to your project (AAR file import instructions)

Changelog

Please check always our changelog to see what we changed in the latest version. In some very rare cases you have to adapt your implementation to be able to use the latest version.

Set up Google Ad Service¶

To set up Google Ad Service just add the following line to your dependencies:

implementation 'com.google.android.gms:play-services-ads:xx.x.x'

Visit Maven Repository to find the latest version of Google Ad Service.

Permissions¶

The only required permission is:

Internet android.permission.INTERNET

Some advertisements needs some special permissions (e.g. GPS, write external storage and etc). ADvantage uses a two-way permission mechanism for example if your app uses GPS but you don't want that ads are using it you can permit it for each instance.

For more details about the ADvantage permissions, visit our Permissions page.

License key and ad positions¶

In order to show the advertisements, each ADvantage instance needs a valid license key, ad position and site identifier.

License key The license key is a unique key for each app and platform provided by the ADvantage sales team.
SITE_ID The site id represents a category/structure on the ad server. This information will be forwarded to the ad server. On some ad server this could be empty.
POSITION The position is linked to a specific ad position on the ad server and will be also forwarded.

License Information

As each ad server has it's own ad position settings, please contact us we will explain them to you in detail.

Select an ad format¶

An ad space is the area where the advertisement will run and show up. An advertisement could be fullscreen or it will use a small portion of the screen and entice the user to interact (touch, wipe, click and etc.) with the advertisement to lead him at the end to a landing page (in the browser) or to the app store.

In the following sections you will see some examples how to implement ADvantage into your project.

Banner ads are rectangular image or text ads that occupy a spot within an app's layout. They stay on screen while users are interacting with the app, and can refresh automatically after a certain period of time. If you're new to mobile advertising, they're a great place to start.

IMPLEMENT A BANNER

Interstitial¶

Interstitials are fullscreen ads that cover the interface of an app until closed by the user. They're best used at natural pauses in the flow of an app's execution, such as in between levels of a game or just after completing a task.

IMPLEMENT AN INTERSTITIAL