Early Access - Integrate Vungle SDK for Android or Amazon v.6.7.0-early1

Before You Begin

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
  • MREC and banner ads require API version 16 or higher
  • Migrated to AndroidX on Android SDK 6.5.1

Download the SDK

Download the Vungle SDK for Android or Amazon here: https://vungle2-cdn-prod.s3.amazonaws.com/sdks/android/early-access/vungle-android-sdk-6.7.0-early1.zip

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/tree/6.7.0-early1

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.

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.early-access:publisher-sdk-android:6.7.0-early1'
 
  implementation 'androidx.core:core:1.1.0'
  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.1.0'

  // Recommended for SDK to be able to get Android Advertising ID
  implementation 'com.google.android.gms:play-services-basement:17.2.1'
  implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
}
JAR
  1. Download the Vungle SDK v. 6.7.0-early1 and unzip it. From the libs folder, copy all the .jar files, and add them to your project libs folder:
    • vungle-android-sdk-6.7.0-early1.jar
    • gson-2.8.5.jar
    • logging-interceptor-3.12.0.jar
    • okhttp-3.12.0.jar
    • okio-1.15.0.jar
    • androidx-vng-moat-mobile-app-kit-2.6.3.jar
  2. 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.7.0-early1.jar')
    
      // Required Third-party Dependencies
      implementation files('libs/gson-2.8.5.jar')
      implementation files('libs/logging-interceptor-3.12.0.jar')
      implementation files('libs/okhttp-3.12.0.jar')
      implementation files('libs/okio-1.15.0.jar')
      implementation files('libs/androidx-vng-moat-mobile-app-kit-2.6.3.jar')
    
      implementation 'androidx.core:core:1.1.0'
      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.1.0'
    
      // Recommended for SDK to be able to get Android Advertising ID
      implementation 'com.google.android.gms:play-services-basement:17.2.1'
      implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
    }
  3. 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="29"
        tools:overrideLibrary="com.moat.analytics.mobile.vng" />
    
    <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" />
        <activity
            android:name="com.vungle.warren.ui.VungleFlexViewActivity"
            android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize|uiMode"
            android:hardwareAccelerated="true"
            android:launchMode="singleTop"
            android:theme="@android:style/Theme.Translucent.NoTitleBar" />
    
        <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>
AAR
  1. Download the Vungle SDK v. 6.7.0-early1 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.7.0-early1.aar
    • gson-2.8.5.jar
    • logging-interceptor-3.12.0.jar
    • okhttp-3.12.0.jar
    • okio-1.15.0.jar
  2. 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.7.0-early1.aar')
    
      // Required Third-party Dependencies
      implementation files('libs/gson-2.8.5.jar')
      implementation files('libs/logging-interceptor-3.12.0.jar')
      implementation files('libs/okhttp-3.12.0.jar')
      implementation files('libs/okio-1.15.0.jar')
    
      implementation 'androidx.core:core:1.1.0'
      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.1.0'
    
      // Recommended for SDK to be able to get Android Advertising ID
      implementation 'com.google.android.gms:play-services-basement:17.2.1'
      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

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

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)
6.5.0 & above Legacy
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
  }
};
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()

Implement Event Listeners

You can use generic callbacks, by implementing LoadAdCallback for ad load events and PlayAdCallback for ad play events, or use inline callbacks when you invoke loadAd and playAd.

LoadAdCallback

6.5.0 & above Legacy
private final LoadAdCallback vungleLoadAdCallback = new LoadAdCallback() { 
  @Override
  public void onAdLoad(String id) { 
    // Ad has been successfully loaded for the placement
  } 

  @Override 
  public void onError(String id, VungleException exception) { 
    // Ad has failed to load for the placement
  }
};
Overridable Methods Description
onAdLoad(String id) Invoked when the ad has been successfully loaded and be played for the placement
onError(String id) Invoked when an error occurs while attempting to play an ad. You will be able to check error message from getLocalizedMessage of VungleException and use getExceptionCode for debugging.

PlayAdCallback

6.6.0 & above Legacy
private final PlayAdCallback vunglePlayAdCallback = new PlayAdCallback() {
  @Override
  public void onAdStart(String id) { 
    // Ad experience started
  }

  @Override
  public void onAdEnd(String id) {
    // Ad experience ended
  }

  @Override
  public void onAdClick(String id) {
    // User clicked on ad
} @Override public void onAdRewarded(String id) { // User earned reward for watching an ad } @Override public void onAdLeftApplication(String id) { // User has left app during an ad experience } @Override public void onError(String id, VungleException exception) { // Ad failed to play } };
Overridable Methods Description
onAdStart(String id) Invoked when the ad is successfully launched and displayed on the device.
onAdEnd(String id) Invoked when the entire ad experience has been completed, just before the control has been returned back to the hosting app.
onAdClick(String id) Invoked when the user has clicked on a video ad or download button.
onAdRewarded(String id) Invoked when the user has completed 80% of the rewarded video and should be rewarded. Rewarding the user should take place here and it will only get triggered for rewarded placements.
onAdLeftApplication(String id) Invoked when the user leaves the app before ad experience is completed, such as opening the Store page for the ad.
onAdError(String id, VungleException exception) Invoked when an error occurs while attempting to play an ad. You will be able to check error message from getLocalizedMessage of VungleException and use getExceptionCode for debugging.

Load an Ad for a Placement

The LoadAdCallback will be notified about the load state for the call to which it was assigned. The SDK only references this callback and does not store it anywhere; it is the responsibility of the caller to ensure that the callback is managed properly.

public static void loadAd(@NonNull final String id, @Nullable LoadAdCallback callback)
// Load Ad Implementation
if (Vungle.isInitialized()) {
  Vungle.loadAd("PLACEMENT_ID", new LoadAdCallback() {
    @Override
    public void onAdLoad(String placementReferenceId) { }

    @Override
    public void onError(String placementReferenceId, VungleException exception) { }
  });
}

Check Ad Availability for a Placement

Use the static method canPlayAdmethod to check if there is an ad available to play for the placement before invoking the playAd method.

public static boolean canPlayAd(@NonNull String id)

Play an Ad

To play an ad, invoke the playAd method with the placement reference ID, optional AdConfig (null if not being used), and a PlayAdCallback event listener, which will be notified of success or errors during ad playback.

public static void playAd(@NonNull final String id, final AdConfig settings, @Nullable final PlayAdCallback listener)

Always check ad availability by calling the canPlayAd method before invoking the playAd method. Because an ad will not render properly if playAd is repeatedly called in quick succession, you must also make sure that you receive either an onAdEnd or an onError callback from the initial playAd call before issuing an additional playAd.

if (Vungle.canPlayAd("PLACEMENT_ID")) { 
  Vungle.playAd("PLACEMENT_ID", null, vunglePlayAdCallback);
}

Re-Initialize SDK When onError Occurs

On rare occurrences, resources can become limited, causing the system to deallocate either part of the Vungle SDK, or some of the third-party dependencies our SDK requires. In such cases, LoadAdCallback and PlayAdCallback fire an onError callback with a VungleException object, with the code VungleException.VUNGLE_NOT_INTIALIZED. This indicates that the Vungle SDK is in an inoperable state and must be re-initialized.

if (e.getExceptionCode() == VungleException.VUNGLE_NOT_INTIALIZED) {
  // Re-initialize Vungle SDK
}

Optional and Advanced Settings

Integrate MREC Ads

Vungle MREC is currently in BETA phase. Please contact your account manager directly for access to ensure a successful launch.

Starting with Vungle SDK version 6.4.11, Vungle supports MREC video ads, which do not require a fullscreen view. The container size to render an MREC ad is 300 x 250, which is the industry standard. MREC video ads can be set anywhere on the screen and the user can continue using the app while the ad is being played.

Load an MREC Ad

Loading an MREC ad is the same as loading a fullscreen ad. However, the placement must be configured to support an MREC feed. Please contact your Vungle account manager to enable MREC for a placement.

Display an MREC Ad

Because the view size is fixed, the container which is used to display the MREC ad must be specified to be 300dp x 250dp, and the view can be placed anywhere on the screen. This container is a RelativeLayOut.

You can place this RelativeLayout anywhere on the screen. You must then call AdConfig.setAdSize to specify the ad size to be AdConfig.AdSize.VUNGLE_MREC and pass this object when calling Vungle.getNativeAd to get the MREC ad object.

Finally, call the addView function to associate the container with the MREC ad. Vungle MREC plays with sound enabled as a default, but you can set the setMuted option to true to start the video muted.

private RelativeLayout mrecContainer = findViewById(...);

AdConfig adConfig = new AdConfig();
adConfig.setAdSize(AdConfig.AdSize.VUNGLE_MREC);
adConfig.setMuted(true);

VungleNativeAd vungleNativeAd = Vungle.getNativeAd("MREC_ID", adConfig, vunglePlayAdCallback);
View nativeAdView = vungleNativeAd.renderNativeView();
mrecContainer.addView(nativeAdView);

Close an MREC Ad

Because you have added the MREC ad view to your container view, you must also remove it, in case the ad view disappears from the screen, the activity or fragment is destroyed, or the parent view container is recycled or destroyed. If you try to play another MREC ad without closing the previous ad, you may see unexpected behavior in your app. Therefore, invoke finishDisplayingAd to end the ad experience. We also recommend that you remove the view onAdEnd event.

private VungleNativeAd vungleNativeAd;

// Calling finishDisplayingAd when you want to finish displaying MREC Ad
// will trigger onAdEnd and will tell you when you can remove the child
// MREC view container 
vungleNativeAd.finishDisplayingAd();

// And removing empty ad view from container
@Override 
public void onAdEnd(String id, boolean completed) {
    …
    parentView.removeView(nativeAdView);
    vungleNativeAd = null;
    …
}

Attach and Detach the State of an MREC Ad

If the user scrolls to a point where the video ad is no longer visible on the screen, you must pause the video, and resume it when it is again visible. To control the pause and resume states, call setAdVisibility from the VungleNativeAd instance, and set it to true when the video is visible and to false when the video goes off screen. The setAdVisibility is not to be confused with View visibility: this setter informs Vungle SDK whether the MREC ad view is visible or not, and depending on it, the SDK pauses or resumes video playback.

  • Pause an MREC ad:
    vungleNativeAd.setAdVisibility(false);
  • Resume an MREC ad:
    vungleNativeAd.setAdVisibility(true);

Integrate Banner Ads

Vungle Banner is currently in BETA phase. Please contact your account manager directly for access to ensure a successful launch.

Vungle supports banner video ads starting with Vungle SDK v6.5.1. The container size to render banner ads can be 320x50, 300x50, or 728x90 (for tablets).


Banner ads can be set anywhere on the screen, and the user can continue using the app while the ad is being played.

Banner Size

Dimensions

AdConfig.AdSize.BANNER

320x50

AdConfig.AdSize.BANNER_SHORT

300x50

AdConfig.AdSize.BANNER_LEADERBOARD

728x90 (for tablets)

Load a Banner Ad

Loading a banner ad works differently than it does for other ad formats. There is a specific Banners API that you use to load, play, and check for ad availability. You must specify the size of the banner that you want to load, and the SDK will automatically refresh it with the time interval that you configured on the dashboard. You must also configure the placement to support a banner feed, so please contact your Vungle account manager to enable banner ads for a placement.

  • Load a banner ad by calling the loadBanner method:
    Banners.loadBanner("BANNER_ID", AdConfig.AdSize.BANNER, vungleLoadAdCallback);
  • Check for banner ad availability by calling the canPlayAd method:
    Banners.canPlayAd(ad.placementReferenceId, AdConfig.AdSize.BANNER);

Display a Banner Ad

Because the view size is fixed, you must specify the container used to display banner ads to be one of the supported sizes: 320x50, 300x50, or 728x90 (for tablets). You can place the view anywhere on the screen. This container is a LayOut. Its size must be equal to or greater than the banner size you are using. You can place this LayOut anywhere on the screen. Then you must pass the size of the banner you are using via the Banners API.

Pass this object when calling Banners.loadBanner to specify the size you are displaying, and use Banners.getBanner to get the Banners ad object. Finally, call the addView method to associate the container with the banner ad.

private RelativeLayout bannerContainer = findViewById(...);
// Check for banner ad availability and display
if (Banners.canPlayAd("BANNER_ID", AdConfig.AdSize.BANNER)) {
  VungleBanner vungleBanner = Banners.getBanner("BANNER_ID", AdConfig.AdSize.BANNER, vunglePlayAdCallback);
  bannerContainer.addView(vungleBanner);
}

Close a Banner Ad

Because the banner ad view has been added to your container view, it must also be removed, in case the ad view disappears from the screen, the activity or fragment is destroyed, or the parent view container is recycled or destroyed. If you try to play another banner ad without closing the previous ad, you may experience unexpected behavior in your app.

vungleBanner.destroyAd();

Advanced Banner Configuration

For most cases, the integration described above is sufficient, and VungleBanner will be managed. However, if the VungleBanner view is inside a list or a RecyclerView, the managed VungleBanner will not work correctly. The moment the user scrolls the ad offscreen and scrolls back, the ad will be finished and no longer there. For such cases, we provide an advanced API for closer control of the VungleBanner. Refer to our main banner integration guide for more information.

Include Google Play Services

Including Google Play Services with your project is optional, but recommended. It enables Vungle to provide a more customized ad experience to your end user. We recommend that you include basement and ads-identifier APIs, and that you use version Google Play Services v11.0.1 or higher.

To include Google Play Services, refer to Google's setup guide. In your app, ensure that the device has a sufficiently updated version of Google Play Services. The Vungle SDK optionally uses the location and ads API from Google Play Services.

  • google.android.gms:play-services-basement:16.0.0 (Recommended)
  • google.android.gms:play-services-ads-identifier:16.0.0 (Required for AAID)

Method Count Reduction

Adding Vungle Android SDK v6 to your project adds approximately 700 core Vungle methods, excluding any transitive dependencies. A full integration including third-party libraries is expected to add less than 4000 methods on average. Consider the following suggestions to reduce the total number of methods added to your project:

  • ProGuard: You can enable ProGuard to shrink your project code. It will discard any unused classes at the time of compilation to make the total method count as small as possible. You can enable it by setting minifyEnabled to true in build.gradle for the appropriate build type, and by providing the rules to keep the classes required by your project.
  • MultiDex: If you are still above a 65K method count, enabling MultiDex may be the only solution provided by Google. You must only configure your project to MultiDex one time, but it will have an impact on build and app startup time.

ProGuard

If you are using ProGuard, add the following rules to your ProGuard configuration file:

# Vungle
-keep class com.vungle.warren.** { *; }
-keep class com.vungle.warren.downloader.DownloadRequest
-dontwarn com.vungle.warren.error.VungleError$ErrorCode
-dontwarn com.vungle.warren.downloader.DownloadRequest$Status
-keepclassmembers enum com.vungle.warren.** { *; }

# Moat SDK
-keep class com.moat.** { *; }
-dontwarn com.moat.**
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
-keepattributes *Annotation*

# Retrofit
-keepattributes Signature, InnerClasses
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
-dontwarn javax.annotation.**
-dontwarn kotlin.Unit
-dontwarn retrofit2.-KotlinExtensions
-keepclassmembers,allowshrinking,allowobfuscation interface * {
    @retrofit2.http.* <methods>;
}

# Okio+OkHttp
-dontwarn okhttp3.**
-dontwarn okio.**
-dontwarn javax.annotation.**
-dontwarn org.conscrypt.**
-keepnames class okhttp3.internal.publicsuffix.PublicSuffixDatabase
-keepclassmembers class * extends com.vungle.warren.persistence.Memorable {
   public <init>(byte[]);
}

Set Minimum Disk Space

Minimum disk space configuration was introduced in Vungle SDK v6.4.11 to determine the limits for available space on a user’s device before the Vungle SDK initializes and fetches ads. The default value for setMinimumSpaceForInit is 51 MB and setMinimumSpaceForAd is 50 MB. The size is entered in bytes.

VungleSettings vungleSettings = new VungleSettings.Builder()
    .setMinimumSpaceForInit(51L * 1024L * 1024L)  // 51 MB
    .setMinimumSpaceForAd(50L * 1024L * 1024L)    // 50 MB
    .build();
  
Vungle.init(appId, getApplicationContext(), initCallback, vungleSettings);

Restrict Use of Device ID

Starting with Vungle Android SDK v6.4.11, you can now restrict the transmission of the Android ID used when the Google Advertising ID is not available.

// Set true to opt out for Android ID collection by SDK or false (default) to opt in
VungleSettings vungleSettings = new VungleSettings.Builder()
    .setAndroidIdOptOut(true)
    .build();
    
Vungle.init(appId, getApplicationContext(), initCallback, vungleSettings);

Ad Configuration Options

You have the option to customize individual ads you play by providing a new adConfig object to playAd. When the AdConfig object is null, the ad plays with the default configuration settings; when it is non-null, its settings override those in the AdConfig setter. The following is an example of how to use AdConfig:

Vungle.playAd(placementReferenceID, adConfig, vunglePlayAdCallback);

The above example uses the adConfig object, which contains customized configuration options. Set the AdConfig object as shown:

object
AdConfig adConfig = new AdConfig();
adConfig.setAdOrientation(AdConfig.AUTO_ROTATE);
adConfig.setMuted(true);
Vungle.playAd(placementReferenceID, adConfig, vunglePlayAdCallback);

The following table lists all the available AdConfig options:

Option

Description

setBackButtonImmediatelyEnabled

'true' if the back button should be enabled before the close ad button appears; 'false' otherwise

setAdOrientation

AdConfig.AUTO_ROTATE if the video ad should auto-rotate; otherwise AdConfig.LANDSCAPE or AdConfig.PORTRAIT to follow video ad orientation

setMuted

'false' if the video should start with its audio settings matching those of your enclosing application; 'true' if it should start muted regardless

setOrdinal

takes an Integer value of ordinal count to track the number of ads that have been played in same session

Note: You may use the same AdConfig object for multiple ads.

Customize Rewarded Ads

The pop-up message dialog for rewarded ads is configurable with the setIncentivizedFields method.

Note: Rewarded ads are in some cases referred to as incentivized ads; both terms always refer to the same kind of ad. In the SDK code and in our Reporting API, we use the term 'incentivized'.
public static void setIncentivizedFields(@Nullable String userID, @Nullable String title, @Nullable String body, @Nullable String keepWatching, @Nullable String close)

List of Valid Placements

We provide a helper method that returns a Collection of Strings containing all valid Placement Reference IDs for the current session.

public static Collection getValidPlacements()

GDPR Recommended Implementation Instructions

As of May 25, 2019, the General Data Protection Regulation (GDPR) will be enforced in the European Union. To comply with GDPR, developers have two options.

  • Option 1 (recommended): Publisher controls the GDPR consent process at the user level, then communicates the user’s choice to Vungle. To do this, developers can collect the user’s consent using their own mechanism, and then use Vungle APIs to update or query the user’s consent status. Refer to the sample code below for details.
  • Option 2: Allow Vungle to handle the requirements. Vungle will display a consent dialog before playing an ad for a European user, and will remember the user’s consent or rejection for subsequent ads.

The updateConsentStatus method (recommended in Option 1) takes the user's consent status and the consent message version as its parameters.

public static void updateConsentStatus(@NonNull Consent status, @NonNull String consentMessageVersion)

The consent status will specify whether the user has OPTED_IN or OPTED_OUT for the message version you displayed. The consentMessageVersion specifies the publisher-controlled consent policy version; this enables you to pool your users by the message version and seek consent again when the GDPR policy changes.

// Usage example of GDPR API
// To set the user's consent status to opted in:
Vungle.updateConsentStatus(Vungle.Consent.OPTED_IN, “1.0.0”);

// To set the user's consent status to opted out:
Vungle.updateConsentStatus(Vungle.Consent.OPTED_OUT, “1.0.0”);

// To find out what the user's current consent status is:
// This will return null if the GDPR Consent status has not been set
// Otherwise, it will return Vungle.Consent.OPTED_IN or Vungle.Consent.OPTED_OUT
Vungle.Consent currentGDPRStatus = Vungle.getConsentStatus();
String consentMessageVersion = Vungle.getConsentMessageVersion();

CCPA Implementation

As of July 1, 2020, California Consumer Privacy Act (CCPA) will be enforced and publishers must updated to Android SDK 6.7.0-early1 to comply with CCPA.

The updateCCPAStatus method takes the user's consent status to specify whether user has OPTED_IN or OPTED_OUT and getCCPAStatus() method returns current CCPA status for the user.

public static void updateCCPAStatus(@NonNull final Consent status)
public static Consent getCCPAStatus()
// Usage example of CCPA API
// To set the user's CCPA status to opted in:
Vungle.updateCCPAStatus(Consent.OPTED_IN);

// To set the user's CCPA status to opted out:
Vungle.updateCCPAStatus(Consent.OPTED_OUT);

// To find out what the user's current consent status is:
Consent currentCCPAStatus = Vungle.getCCPAStatus();

Hardware Acceleration

Hardware acceleration is enabled by default for your application if your target API level is set to 14 or above. This option must be enabled for the SDK to properly show Dynamic Template and MREC ads. Make sure this option is set to 'true' at the application level of your project:

<application android:hardwareAccelerated="true" ...>

Retrieve the SDK Version Number

To programmatically retrieve the SDK version number at runtime (this useful in internal mediation), Vungle provides the following String:

com.vungle.warren.BuildConfig.VERSION_NAME

Exception Codes for Debugging

InitCallback, PlayAdCallback, and LoadAdCallback will have a VungleException code when the onError callback fires. You can use the code to debug or take actions to correct the issue programmatically.

if (exception.getExceptionCode() == VungleException.VUNGLE_NOT_INTIALIZED) {
  // Call routine to initialize SDK
}
Exception Code Description
CONFIGURATION_ERROR A configuration error occurred. Check your app ID and placement reference IDs, and try again when network connectivity is available.
NO_SERVE Ad server found no advertisements for your current bid. Please try again later. This exception is expected behavior.
UNKNOWN_ERROR An unknown error occurred. This exception should be rare.
AD_EXPIRED The advertisement in the cache has expired and can no longer be played. Please load another ad.
MISSING_REQUIRED_ARGUMENTS_FOR_INIT Please ensure all parameters for Vungle.init() marked as NonNull are provided, as they are essential for the SDK to function.
APPLICATION_CONTEXT_REQUIRED Please provide the application Context so that our SDK can continue to support our API beyond the Activity lifecycle.
OPERATION_ONGOING There is already an ongoing operation for the action you requested. Please wait until the operation completes before starting another.
VUNGLE_NOT_INTIALIZED Vungle is not initialized, or no longer initialized. Please call Vungle.init() to reinitialize.
AD_UNABLE_TO_PLAY Unable to play advertisement.
AD_FAILED_TO_DOWNLOAD Advertisement failed to download.
PLACEMENT_NOT_FOUND Placement is not valid.
SERVER_RETRY_ERROR Remote server responded with HTTP Retry-After, the SDK will retry this request.

Configure Auto Backup for JAR Integration

The "allow backup" setting is enabled by default for your application for API 23 or higher. The backup rule ensures that all application data is backed up for proper operation of the Vungle SDK and of the app itself. If you have not disabled the "allow backup" setting or specified your own backup rules, you must provide additional XML rules to define which files in our SDK file system should be excluded from automatic backup.

Vungle Exclusion Rules

<full-backup-content>
    <exclude domain="file" path="vungle" />
    <exclude domain="file" path="vungle_cache" />
    <exclude domain="external" path="vungle_cache" />
    <exclude domain="database" path="vungle_db" />
    <exclude domain="sharedpref" path="com.vungle.sdk.xml" />
</full-backup-content>

Gradle Integration with Developer Backup Rules

  1. Add Vungle SDK exclusion rules to the existing .xml file that has your app’s own exclusion rules.
  2. Configure fullBackupContent to be replaced on the application level and add the Vungle SDK exclusion rule to the existing .xml.

JAR Integration with Developer Backup Rules

  1. Create a new XML file with Vungle exclusion rules.
  2. Place the .xml file under the res/xml directory.
  3. Add fullBackupContent in the application tag of AndroidManifest.xml with the file name of the .xml file you created above.
    <application
        android:fullBackupContent="@xml/vungle_backup_rule">

Disable Auto Backup

If backup is not required for your app, you can simply disable it on the application tag:

<application 
    android:allowBackup="false" >
Powered by Creativity Driven by Performance Sign Up Here

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!

Was this article helpful?