Android SDK

2639 views 14/10/2018 Shay Karpeles 0

Getting Started

13 Sept, 2018 - version 4.3.6

This document details the process of integrating YouAppi’s SDK with your Android app.

If you have any questions, please, feel free to email us: support@youappi.com

The basic steps of integration are:

  • Add our SDK AAR and dependencies to your project.
  • Init the SDK.
  • Load an ad.
  • Show an ad.

Requirements:

Minimum API level: 16, Android 4.1

Please, note that SDK can access some of user’s private information, so, make sure you have read this part carefully. 

Integration

Integrate using AAR file

Our latest SDK version can be downloaded as a ZIP file from the following URL:

YouAppi Android SDK

The ZIP file contains:

  • SDK AAR file – youappi-sdk-android-moat.aar – YouAppi’s SDK
  • SDK AAR file – youappi-sdk-android-admob.aar – YouAppi’s AdMob adapter
  • SDK AAR file – youappi-sdk-android-mopub.aar – YouAppi’d MoPub adapter
  • Copy youappi-sdk-android-moat.aar file to the apps\libs folder of your project.
  • Add the following to the project build.gradle file inside the repositories section:
    repositories {
        flatDir {
            dirs 'libs'
        }
    }
  • Add to your app build.gradle file the following under dependencies section:
    dependencies {
        implementation name:'youappi-sdk-android-moat', ext:'aar'
        implementation 'com.google.code.gson:gson:2.6')
    }

Note: If Manifest Merger is disabled, the following items need to be added to the AndroidManifest.xml file:

  • Add AdActivity activity to <application> tag :
    <activity android:name="com.youappi.sdk.AdActivity"
       android:configChanges="screenSize|orientation"/>
  • These permissions should be added if your app is running on older devices:
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Integrate using repository

  • Add the following to the project build.gradle file inside the repositories section:
    maven { url "http://repository.youappi.com/repository/release" }
    
  • Add to your app build.gradle file the following under dependencies section:
    dependencies {
         implementation "com.youappi.sdk:youappi-sdk-android-moat:4.3.6"
    }

Using the SDK

  • Initialize YouAppi SDK as soon as your app loads with the app token, provided by YouAppi, and GDPR user consent. If your user is NOT subject to the GDPR rules (e.g.: a EU residence), please,  make sure userConsent value is ‘true’ in order to get relevant ads:
    YouAPPi.init(context, "<YOUR_APP_TOKEN>", userConsent);
  • Please note: it is strongly recommended to initialize YouAppi SDK in the onCreate method of the Application object of your app. It will ensure YouAppi SDK instance is always properly initialized. Here is an example:
    import android.app.Application;
    import com.youappi.sdk.YouAPPi;
                
    public class YouAppApplication extends Application {
                    
          private static final String DEMO_TOKEN = "<YOUR_APP_TOKEN>;
     
          @Override
          public void onCreate() {
                super.onCreate();
     
                YouAPPi.init(this, DEMO_TOKEN, userConsent);
          }
    }
    
  • Also, update the corresponding manifest.xml with the Application class name:
    <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="com.youappi.sdk.demo">
    
        <application
            android:name = ".YouAppApplication"
            android:allowBackup="true"
            android:icon="@mipmap/ic_launcher"
            android:label="@string/app_name"
            ...
            ...
        </application>
    </manifest>
  • Create an ad instance for one of YouAppi’s products:
    • Rewarded Video
    • Interstitial Video
    • Interstitial Ad
    YARewardedVideoAd rewardedVideoAd = YouAPPi.getInstance().rewardedVideoAd("test_rewarded_video_ad");
    YAInterstitialVideoAd interstitialVideoAd = YouAPPi.getInstance().interstitialVideoAd("test_interstitial_ad");
    YAInterstitialAd interstitialAd = YouAPPi.getInstance().interstitialAd("test_interstitial_ad");
  • Please note: YouAppi ad unit id is created and controlled by the app developer. The ad unit id later appears in reports and helps to analyze performance for each ad unit. Any arbitrary value can be selected for ad unit id as long as it is constructed from:
    • letters (lowercase, uppercase)
    • numbers
    • underscores.
  • Load an ad (for example, a rewarded video ad):

    rewardedVideoAd.load();
  • Show an ad:

    rewardedVideoAd.show();

Custom parameters and server-to-server callback (optional)

YouAppi SDK supports customer parameters and server-to-server callback. Custom parameters could be passed during the ad request and received upon user’s completion event as a part of the callback string (server-to-server completion callback).

Parameter Name Description Value Type Provided by
user_id The unique identifier of the user to be rewarded. String Publisher
reward_type The name of the virtual item to be awarded. String Publisher
reward_value The number of credit units to be awarded to the user. Integer Publisher
reward_id A unique identifier of the commission event. String YouAppi

Callback URL example:
http://www.app.com?appUserId={user_id}&RewardValue={reward_value}&RewardType={reward_type}&RewardId={reward_id}

You can use YAAdRequest object to add custom parameters as <key, value> to your ad request before loading an ad:

YaAdRequest adRequest = new YAAdRequest();
adRequest.addCustomParam("param_key", "param_value");
rewardedVideoAd.setAdRequest(adRequest);

Implementation example for Rewarded Video

Please note: this example is for rewarded video. Other products work in a similar way.

  • Create a rewarded video instance:
    YARewardedVideoAd rewardedVideoAd = YouAPPi.getInstance().rewardedVideoAd("test_rewarded_video_ad");
  • Add rewarded video event listener:

    rewardedVideoAd.setRewardedVideoAdListener(new YARewardedVideoAd.RewardedVideoAdListener() {
                @Override
                public void onRewarded(String s) {
                    
                }
     
                @Override
                public void onVideoStart(String s) {
     
                }
     
                @Override
                public void onVideoEnd(String s) {
     
                }
     
                @Override
                public void onVideoSkipped(String s, int i) {
     
                }
     
                @Override
                public void onCardShow(String s) {
     
                }
     
                @Override
                public void onCardClose(String s) {
     
                }
     
                @Override
                public void onCardClick(String s) {
     
                }
     
                @Override
                public void onLoadSuccess(String s) {
     
                }
     
                @Override
                public void onLoadFailure(String s, YAErrorCode yaErrorCode, Exception e) {
     
                }
     
                @Override
                public void onShowFailure(String s, YAErrorCode yaErrorCode, Exception e) {
     
                }
     
                @Override
                public void onAdStarted(String s) {
     
                }
     
                @Override
                public void onAdEnded(String s) {
     
                }
            });
  • Add custom parameters (if needed) and load rewarded video ad:
    YAAdRequest adRequest = new YAAdRequest();
    adRequest.addCustomParam("user_id", "user100");
    adRequest.addCustomParam("reward_value", "25");
    adRequest.addCustomParam("reward_type", "coins")
    rewardedVideo.setAdRequest(adRequest);
    rewardedVideoAd.load();
  • Once ad is loaded, the event onLoadSuccess is called and it can be shown by calling:

    rewardedVideoAd.show();
  • Ad availability can also be checked by calling:

    rewardedVideoAd.isAvailable();

    If you’re using proguard in your application the following entries should be added to your proguard file:

    -keep class com.google.gson.**{ *;}
    -keep class com.google.android.gms.**{*;}
    -keep class com.youappi.sdk.**{*;}
    -keep interface com.youappi.sdk.**{*;}
    -keep enum com.youappi.sdk.**{*;}
    -keepclassmembers class * {
       @android.webkit.JavascriptInterface <methods>;
    }

User’s Private Information

For providing more relevant ads according to user’s interests YouAppi collects user’s installed packages information. By default, the user’s explicit consent flag value is ‘false’. By choosing ‘true’ you allow YouAppi to collect this information which helps us to optimise yield and raise eCPM. Make sure to post a privacy policy in both the designated field in the Play Developer Console and from within the Play distributed app itself to avoid violation of Google’s Developer Distribution Agreement.

User’s explicit consent can be set the following way:

YouAPPi.getInstance().sendApps(true);

GDPR User’s Consent

The userConsent flag  value should be determined by the app developer according to the User’s response to a Consent Request and according to the user being subject to the GDPR rules (e.g.: an EU residence). The userConsent flag value signals to YouAppi the permission to process and store the user’s Personal Information (e.g.: Advertising ID and IP address). In case that the flag value is false, YouAppi may decide not to respond to the ad request, since the user cannot be detected and his actions cannot be attributed to the user and hence also to YouAppi and to the app developer.

GDPR user consent can be passed in the following ways:

  • It is mandatory to pass user consent in SDK init:
YouAPPi.init(context, "<YOUR_APP_TOKEN>", userConsent);
  • User’s consent can be set by using:
YouAPPi.getInstance().setUserConsent(userConsent);
  • If the user is known to be in an age restricted class (e.g.: under the age of 16 in some countries or under the age of 13 in other countries ) then the age restricted indication should be passed:
YouAPPi.getInstance().setAgeRestrictedUser(ageRestrictedUser);

Logging and troubleshooting

After initializing the SDK you can set LogListener to get detailed log events from YouAppi’s SDK:

YouAPPi.getInstance().setLogListener(new Logger.LogListener()
   {
       @Override
       public void log(String tag, String message)
       {
           // This will be called each time YouAppi SDK generates a log message.
       }
   });

Load and Show best practices

  • Make sure to init the SDK as soon as the app starts. It might take few seconds to complete the init process.
  • Make sure to load the ad about 30 seconds before you want to show it since it takes time for the ad and assets to be prepared.
  • Make sure to show an ad as close as possible to its load, in order to have a better fill rate and relevant ads.
  • Make sure not to wait too long before showing an ad, since the ad will be expired 5 hours after being called for. In other words, “show” must be performed no more than 5 hours after the “load”.
  • Use ad event listeners in order to be notified when an ad is ready to be shown.
  • Use ad event listeners to handle load and show.
  • Loading an ad too many times without showing it might cause YouAppi servers to block the SDK from requests.

Demo App

A demo app showing a simple usage of the SDK can be found in the following bitbucket repository:

https://bitbucket.org/youappi/youappi-sdk-android-demo-simple

The demo app contains 3 modules:

  • app-demo – Shows how to use YouAppi’s SDK
  • app-demo-admob – Shows how to use YouAppi’s SDK with AdMob adapter
  • app-demo-mopub – Shows how to use YouAppi’s SDK with MoPub adapter

Please make sure to read the README.md file for further instructions.

Tags: