Migrating the Vungle Android SDK from v. 5 to v. 6

Welcome to migration guide for Vungle Android SDK v6! The new SDK has been completely rewritten to be both robust and lightweight. Use this document to guide you through the SDK upgrade because there are significant changes in both API and integration details. If this is a brand new integration and you are not migrating from the v5 SDK, use the Integrating Vungle Android SDK v6 guide instead of this one.

In this article:

Before You Begin 

Requirements

  • Android 4.0 (Ice Cream Sandwich - API version 14) or later
  • Amazon OS 5.4 and above

Sample App

Step 1. Change Vungle SDK in Your Project

Depending on your project setup, use the AAR integration via Maven or JAR for manual integration.

Option 1. Gradle Integration 

dependencies {
    // Vungle SDK
    compile 'com.github.vungle:vungle-android-sdk:6.3.17'

    // Recommended Google Play Services
    compile 'com.google.android.gms:play-services-basement:15.0.1'

    // Optional Google Play Services
    compile 'com.google.android.gms:play-services-ads-identifier:15.0.1'
    compile 'com.google.android.gms:play-services-location:15.0.1'
}

Skip to "Step 2. Import the Vungle SDK."

Option 2. JAR Integration

Download Vungle SDK v6 and replace the old Vungle SDK and third-party dependency JAR files with the new SDK and libraries. Please pay attention to the addition and removal of required libraries, as well as version updates.

v5 Libraries v6 Libraries
image3.png Screen_Shot_2018-08-16_at_7.14.46_AM.png

Compile all JAR files from the SDK package download.


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

    // Required Third-party Dependencies
    compile files('libs/converter-gson-2.2.0.jar')
    compile files('libs/fetch-1.1.5.jar')
    compile files('libs/gson-2.7.jar')
    compile files('libs/logging-interceptor-3.7.0.jar')
    compile files('libs/okhttp-3.7.0.jar')
    compile files('libs/okio-1.12.0.jar')
    compile files('libs/retrofit-2.2.0.jar')
    compile files('libs/VNG-moat-mobile-app-kit-2.2.0.jar')

    // Support library
    compile 'com.android.support:support-v4:26.1.0'

    // Recommended Google Play Services
    compile 'com.google.android.gms:play-services-basement:15.0.1'

    // Optional Google Play Services
    compile 'com.google.android.gms:play-services-ads-identifier:15.0.1'
    compile 'com.google.android.gms:play-services-location:15.0.1'
}

Modify your AndroidManifest.xml. 

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

<!--Optional Permissions-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!--Vungle Activities-->
<activity
android:name="com.vungle.warren.ui.VungleActivity"
android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize"
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"
android:hardwareAccelerated="true"
android:launchMode="singleTop"
android:theme="@android:style/Theme.Translucent.NoTitleBar" />

Step 2. Import the Vungle SDK 

// v5 Import SDK
import com.vungle.publisher.*;

// v6 Import SDK
import com.vungle.warren.*; 

Step 3. Initialize the Vungle SDK

Previously, to initialize, you had to first grab a Vungle SDK instance and issue init(). This method took the Vungle Application ID, array of string containing the Placement Reference IDs and VungleInitListener, like this: 

// v5 Initialization
public void init(@NonNull Context context, @NonNull String vungleAppId, @NonNull @Size(min = 1) String[] placementReferenceIds, @Nullable VungleInitListener initListener)

Starting with v6.3.12, we have removed the requirement for passing all placement reference ID to be used in the session during the initialization. SDK initialization can now be done without passing Collection of placdement reference ID and all active placements for the application ID will be usable to play and load ad. You can still use the legacy API, but it is planned to be deprecated in the future.

// New v6 API
public static void init(@NonNull String appId, @NonNull Context context, @NonNull InitCallback callback)

// Legacy v6 API
@Deprecated
public static void init(@NonNull final Collection placements, @NonNull String appId, @NonNull Context context, @NonNull InitCallback callback)

The initialization method takes the following parameters:

  • Vungle Application ID
  • Application context
  • InitCallback
    • onSuccess: notifies when SDK has successfully initialized
    • onError: notifies when the initialization has failed
      • throws IllegalArgumentException if InitCallback is null
      • throws VungleException if required arguments are missing or invalid
    • onAutoCacheAdAvailable: notifies when the auto-cached placement has an ad available to play

The onAutoCacheAdAvailablecallback is available as part of the initialization callback because the SDK will continuously attempt to cache an ad for the auto-cached placement whenever an ad is not pre-cached. This includes when the SDK is started for the first time or when the pre-cached ad for the placement has been played. This will remain true until the process dies or the Vungle instance is reclaimed by garbage collection. For all other placements that are not auto-cached placements, loadAd must be explicitly issued as described in “Step 5. Load an Ad.” 

// v6 Initialization
Vungle.init(appId, getApplicationContext(), new InitCallback() {
   @Override
   public void onSuccess() {
       // Initialization has succeeded and SDK is ready to load an ad or play one if there
       // is one pre-cached already
   }

   @Override
   public void onError(Throwable throwable) {
       // Initialization error occurred - throwable.getMessage() contains error message
   }

   @Override
   public void onAutoCacheAdAvailable(String placementId) {
       // Callback to notify when an ad becomes available for the auto-cached placement
       // NOTE: This callback works only for the auto-cached placement. Please use
       // LoadAdCallback interface for other placements
   }
};

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

public static boolean isInitialized() 

Step 4. Event Listener

The global VungleAdEventListener in v5 SDK has been replaced with two independent callbacks for load and play events in SDK v6. Please remove the VungleAdEventListener implementation for SDK v5 from your project: 

// Remove v5 Event Listener
public class FirstActivity extends android.app.Activity {

    private final VungleAdEventListener vungleListener = new VungleAdEventListener(){

        @Override
        public void onAdEnd(String placementReferenceId, boolean wasSuccessfulView, boolean wasCallToActionClicked) { }

        @Override
        public void onAdStart(String placementReferenceId) { }

        @Override
        public void onUnableToPlayAd(String placementReferenceId, String reason) { }

        @Override
        public void onAdAvailabilityUpdate(String placementReferenceId, boolean isAdAvailable) { }
    };

    @Override
    public void onDestroy() {
        vunglePub.clearEventListeners();
        super.onDestroy();
    };
}

Implement LoadAdCallback for ad load events and PlayAdCallback for ad play events now if you want to use generic callback for all events. Otherwise, skip to “Step 5. Load an Ad” to implement inline callbacks. 

// Implement v6 LoadAdCallback
private final LoadAdCallback vungleLoadAdCallback = new LoadAdCallback() {
    @Override
    public void onAdLoad(String placementReferenceId) {
        // Placement reference ID for the placement to load ad assets
    }

    @Override
    public void onError(String placementReferenceId, Throwable throwable) {
        // Placement reference ID for the placement that failed to download ad assets
        // Throwable contains error message
    }
};

 

// Implement v6 PlayAdCallback
private final PlayAdCallback vunglePlayAdCallback = new PlayAdCallback() {
    @Override
    public void onAdStart(String placementReferenceId) {
        // Placement reference ID for the placement to be played
    }

    @Override
    public void onAdEnd (String placementReferenceId, boolean completed, boolean isCTAClicked) {
        // Placement reference ID for the placement that has completed ad experience
        // completed has value of true or false to notify whether video was
        // watched for 80% or more
        // isCTAClkcked has value of true or false to indicate whether download button
        // of an ad has been clicked by the user
    }

    @Override
    public void onError(String placementReferenceId, Throwable throwable) {
        // Placement reference ID for the placement that failed to play an ad
        // Throwable contains error message
    }
};

Step 5. Load an Ad

Loading an advertisement is essentially the same in both versions except for the major distinction that in v6, a per-load callback is allowed instead of depending on the global VungleAdEventListener from v5. The LoadAdCallback will be notified about the load state for the call to which it was assigned. The v6 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. 

// v5 loadAd
public void loadAd(@NonNull String placementReferenceId)

// v6 loadAd
public static void loadAd(@NonNull final String id, @Nullable LoadAdCallback callback) 

The SDK manages the ad asset download for the auto-cached placement, so there is no need to invoke this method for the auto-cached placement. For all other placements, the loadAd method must be invoked and completed successfully before the SDK can play an ad for the placement. The onAdLoad callback will be triggered when this happens. 

// v6 Load Ad Implementation
if (Vungle.isInitialized()) {
   Vungle.loadAd("PLACEMENT_ID", new LoadAdCallback() {
       @Override
       public void onAdLoad(String placementReferenceId) { }

       @Override
       public void onError(String placementReferenceId, Throwable throwable) { }
   };
}

Step 6. Check Ad Availability

Check for availability has remained essentially the same as in v5, with the only difference being that the method is now a static method instead of an instance method. 

 // v5 isAdPlayable
public boolean isAdPlayable(@NonNull final String placementReferenceId)

// v6 canPlayAd
public static boolean canPlayAd(@NonNull String id) 

Step 7. Play an Ad

Similar to the change in loading an ad, playing an ad requires the same information as in v5, with the option to pass a PlayAdCallback to the method, which will be notified of success or errors during ad playback. 

// v5 playAd
public void playAd(@NonNull String placementReferenceId, @Nullable AdConfig adConfig)

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

You should always check ad availability by calling the canPlayAd method before invoking the playAd method. You must also make sure that an additional playAd is not issued before your receive an onAdEnd or an onError callback from the initial playAd call, because the ad will not render properly if playAd is repeatedly called in quick succession. 

// v6 Play Ad Implementation
if (Vungle.canPlayAd("PLACEMENT_ID")) {
    Vungle.playAd("PLACEMENT_ID", new AdConfig, new PlayAdCallback() {
        @Override
        public void onAdStart(String placementReferenceId) { }

        @Override
        public void onAdEnd(String placementReferenceId, boolean completed, boolean isCTAClicked) { }

        @Override
        public void onError(String placementReferenceId, Throwable throwable) { }
    });
}

Step 8. Configuration Options

Ad Playing Options

The following table shows all the available AdConfig options. 

Option

Description

setBackButtonImmediatelyEnabled

true if back button should be enabled before ad close button appears, false otherwise

setFlexViewCloseTime

takes an Integer value that is greater or equal to 0 that specifies time in seconds for Flex-View ad to automatically close itself

setAutoRotate

true if the video ad is supposed to auto-rotate, false to follow video ad orientation

setMuted

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

setOrdinal

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

Customizing Rewarded Ads

The pop-up message dialog for rewarded ads was configurable with the AdConfig object in v5, but v6 provides a new method, setIncentivizedFields, instead. 

public static void setIncentivizedFields(@Nullable String userID, @Nullable String title, @Nullable String body, @Nullable String keepWatching, @Nullable String close) 

Close Flex-View Ad

Flex-View can be programmatically closed by issuing the closeFlexViewAd method with the Placement Reference ID that is currently playing the Flex-View ad. 

public static boolean closeFlexViewAd(@NonNull final String placementReferenceId) 

List of Valid Placements

A helper method that returns Collection of String containing all valid Placement Reference IDs for the current session. 

public static Collection<String> getValidPlacements() 

ProGuard Rules

# Vungle
-keep class com.vungle.warren.** { *; }
-dontwarn com.vungle.warren.error.VungleError$ErrorCode

# Moat SDK
-keep class com.moat.** { *; }
-dontwarn com.moat.**

# Okio
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement

# Retrofit
-dontwarn okio.**
-dontwarn retrofit2.Platform$Java8

# Gson
-keepattributes Signature
-keepattributes *Annotation*
-dontwarn sun.misc.**
-keep class com.google.gson.examples.android.model.** { *; }
-keep class * implements com.google.gson.TypeAdapterFactory
-keep class * implements com.google.gson.JsonSerializer
-keep class * implements com.google.gson.JsonDeserializer

# Google Android Advertising ID
-keep class com.google.android.gms.internal.** { *; }
-dontwarn com.google.android.gms.ads.identifier.**

GDPR Recommended Implementation Instructions

As of May 25th, 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 GDPR Recommended Implementation Instruction section 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 (as recommended in Option 1) takes user consent status and 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 being displayed by the publisher. The consentMessageVersion indicates publisher controlled consent policy version to allow publisher getting consent again when GDPR policy changes by pooling users by the message version.

// 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 currentStatus = Vungle.getConsentStatus();
String consentMessageVersion = Vungle.getConsentMessageVersion();

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 Throwable object with a code of ‘VungleException.VUNGLE_NOT_INTIALIZED’. This indicates that the Vungle SDK is an inoperable state and must be re-initialized. 

@Override
public void onError(String placementReferenceID, Throwable throwable) { 
    try {
        VungleException ex = (VungleException) throwable;

        if (ex.getExceptionCode() == VungleException.VUNGLE_NOT_INTIALIZED) {
            initializeVungleSDK();
        }
    } catch (ClassCastException cex) {
        Log.d(LOG_TAG, cex.getMessage());
    }
}
Have more questions? Submit a request

Comments