Integrate Vungle SDK for Android or Amazon

David Kim

April 02, 2021 06:56

Before You Begin

The Vungle SDK has been built and tested up to API version 30, Android 11.

Requirements

The integration requires a Vungle account, so create a Vungle account if you haven’t already done so, and create a new Android or Amazon app in your account. Refer to the Add Your Apps and Placements section of our Using the Publisher Dashboard article to learn how to set up placements in the Vungle dashboard.
Android 4.0 (Ice Cream Sandwich - API version 14 or higher)
Amazon OS 5.4 or higher
Your platform must be AndroidX on Android SDK 6.5.1 or higher

Download the SDK

Download the Vungle SDK for Android or Amazon: https://publisher.vungle.com/sdk/sdks/android

Reference: Sample App and Java Doc

Sample app: Refer to the sample app we have provided as you integrate: https://github.com/Vungle/Android-SDK

JavaDoc: https://vungle.github.io/vungle-android-sdk/javadoc

Step 1. Include the Vungle SDK in Your Project

You can integrate the Vungle SDK either as a Gradle dependency, or manually using a JAR or AAR integration.

// API version compatibility
minSdkVersion 14
compileSdkVersion 30
targetSdkVersion 30

Gradle

Open the project-level build.gradle, and ensure that the JCenter details are as shown here:

allprojects {
  repositories {
    jcenter()
  }
}

Open the app-level build.gradle file for your app, and add compile dependencies in the dependencies section.

buildscript {
  repositories {
    jcenter()
  }
}

dependencies { 
  // Vungle SDK
  implementation 'com.vungle:publisher-sdk-android:6.9.1'
 
  implementation 'androidx.core:core:1.3.2'
  implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0'

  // When appcompat is being used, core and localbroadcastmanager are the dependencies
  // that is getting included
  // implementation 'androidx.appcompat:appcompat:1.2.0'

  // Recommended for SDK to be able to get Android Advertising ID
  implementation 'com.google.android.gms:play-services-basement:17.5.0'
  implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
}

JAR

Download the Vungle SDK and unzip it. From the libs folder, copy all the .jar files, and add them to your project libs folder:
- vungle-android-sdk-6.9.1.jar
- gson-2.8.6.jar
- okhttp-3.12.12.jar
- okio-1.15.0.jar

Open the app-level build.gradle file for your app, and add other dependencies in the dependencies section.

dependencies {
  // Vungle SDK
  implementation files('libs/vungle-android-sdk-6.9.1.jar')

  // Required Third-party Dependencies
  implementation files('libs/gson-2.8.6.jar')
  implementation files('libs/okhttp-3.12.12.jar')
  implementation files('libs/okio-1.15.0.jar')

  implementation 'androidx.core:core:1.3.2'
  implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0'

  // When appcompat is being used, core and localbroadcastmanager are the dependencies
  // that is getting included
  // implementation 'androidx.appcompat:appcompat:1.2.0'

  // Recommended for SDK to be able to get Android Advertising ID
  implementation 'com.google.android.gms:play-services-basement:17.5.0'
  implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
}

Update your AndroidManifest.xml by adding the following lines and assigning the application item name to your application class name:

<uses-sdk
    android:minSdkVersion="14"
    android:targetSdkVersion="30" />

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="18" />

<application
    android:fullBackupContent="@xml/vungle_backup_rule"
    android:hardwareAccelerated="true"
    android:supportsRtl="true" >
    <activity
        android:name="com.vungle.warren.ui.VungleActivity"
        android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize|uiMode"
        android:launchMode="singleTop"
        android:theme="@android:style/Theme.NoTitleBar.Fullscreen" />

    <receiver
        android:name="com.vungle.warren.NetworkProviderReceiver"
        android:enabled="false" >
        <intent-filter>
            <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
            <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
    </receiver>

    <provider
        android:name="com.vungle.warren.utility.VungleProvider"
        android:authorities="${applicationId}.vungle-provider"
        android:exported="false" />
</application>

Include Vungle exclusion rules to allow fullBackupContent.

AAR

Download the Vungle SDK and unzip it. From the libs folder, copy SDK .aar and all .jar dependencies, and add them to your project libs folder:
- vungle-android-sdk-6.9.1.aar
- gson-2.8.6.jar
- okhttp-3.12.2.jar
- okio-1.15.0.jar

Open the app-level build.gradle file for your app, and add other dependencies in the dependencies section.

dependencies {
  // Vungle SDK
  implementation files('libs/vungle-android-sdk-6.9.1.aar')

  // Required Third-party Dependencies
  implementation files('libs/gson-2.8.6.jar')
  implementation files('libs/okhttp-3.12.12.jar')
  implementation files('libs/okio-1.15.0.jar')

  implementation 'androidx.core:core:1.3.2'
  implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0'

  // When appcompat is being used, core and localbroadcastmanager are the dependencies
  // that is getting included
  // implementation 'androidx.appcompat:appcompat:1.2.0'

  // Recommended for SDK to be able to get Android Advertising ID
  implementation 'com.google.android.gms:play-services-basement:17.5.0'
  implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
}

Step 2. Import the Vungle SDK

import com.vungle.warren.Vungle;
import com.vungle.warren.AdConfig;              // Custom ad configurations
import com.vungle.warren.InitCallback;          // Initialization callback
import com.vungle.warren.LoadAdCallback;        // Load ad callback
import com.vungle.warren.PlayAdCallback;        // Play ad callback
import com.vungle.warren.VungleNativeAd;        // MREC ad
import com.vungle.warren.Banners;               // Banner ad
import com.vungle.warren.VungleBanner;          // Banner ad
import com.vungle.warren.Vungle.Consent;        // GDPR consent
import com.vungle.warren.VungleSettings         // Minimum disk space
import com.vungle.warren.error.VungleException  // onError message

Step 3. Add Code

Initialize the SDK

public static void init(@NonNull final String appId,
                        @NonNull final Context context,
                        @NonNull final InitCallback callback)

public static void init(@NonNull final String appId,
                        @NonNull final Context context,
                        @NonNull final InitCallback callback,
                        @NonNull final VungleSettings settings)

The initialization method takes the following parameters:

Vungle application ID
Application context
InitCallback
- onSuccess: notifies when the SDK has successfully initialized
- onError: notifies when the initialization has failed
  - Throws IllegalArgumentException if InitCallback is null.
- onAutoCacheAdAvailable: notifies when the auto-cached placement has an ad available to play
VungleSettings (optional)
- Minimum disk space - Configure minimum space available on device for SDK initialization and operation
- Restrict Android ID - Configure restriction of Android device ID usage

Vungle.init(appId, getApplicationContext(), new InitCallback() {
  @Override
  public void onSuccess() {
    // SDK has successfully initialized
  }

  @Override
  public void onError(VungleException exception) {
    // SDK has failed to initialize
  }

  @Override
  public void onAutoCacheAdAvailable(String placementId) {
    // Ad has become available to play for a cache optimized placement
  }
};

// 6.4.x & below
Vungle.init(appId, getApplicationContext(), new InitCallback() {
  @Override
  public void onSuccess() {
    // SDK has successfully initialized
  }

  @Override
  public void onError(Throwable throwable) {
    // SDK has failed to initialize
  }

  @Override
  public void onAutoCacheAdAvailable(String placementId) {
    // Ad has become available to play for a cache optimized placement
  }
};

Overridable Methods	Description
`onSuccess()`	Invoked when SDK has successfully initialized and is ready to load an ad or play one if there
`onError(VungleException exception)`	Invoked when an error occurs while attempting to initialize the SDK. You will be able to check error message from `getLocalizedMessage` of `VungleException` and use `getExceptionCode` for debugging.
`onAutoCacheAdAvailable(String placementId)`	Invoked when an ad has become available to play for a cache optimized placements. Publisher are still expected to explicitly issue `loadAd` for cache optimized placements as described in Load an Ad for a Placement.

You can check whether the Vungle SDK is initialized anytime by calling the isInitialized method:

public static boolean isInitialized()

Integrate Ad Formats

Complete your SDK integration for each ad format you plan to display in your app. Refer to our instructions for each ad format:

Further Customize Your Ads

Follow the instructions in our Advanced Settings article to fine-tune your app's integration with additional configuration options, such as GDPR, CCPA implementation, and many other settings.