Get Started with Vungle SDK v. 6 - Unity

Contents

 

Before You Begin

  • The Vungle Unity Plugin for iOS supports:
    • iOS 8
    • Unity 4 and Unity 5.4.1 or higher
    • The Vungle SDK requires that you link the WebKit.framework framework to your project. If you are developing for IOS 7, you must set this framework to 'Optional'. To do this, click on your project in Project Navigator and go to GeneralLinked Frameworks and Libraries. Select WebKit.framework and set the Status to ‘Optional’.

  • The Vungle Unity Plugin for Android:
    • requires Java 1.7 for Android
    • supports both Unity 4 and Unity 5.3.2 and higher

  • The Vungle Unity Plugin for Windows:
    • Windows (Universal 8.1 or Phone 8.1) supports Unity 4 and Unity 5.3.2+
    • Windows 10 UWP supports Unity 5.3.2+
    • Before you continue with the rest of this article, first follow the instructions in "Preparing Vungle Windows SDK v.2.0+ for the Unity Plugin". Then return here and complete the remaining steps.

  • Download our sample app at https://github.com/Vungle/Unity-Plugin/tree/sdk6.

 

Step 1. Set Up Your Unity Project with the Vungle Unity Plugin

Add the Vungle Unity Plugin to your Unity Project

With your project open in Unity, double-click the downloaded VunglePlugin.unitypackage file to add the Vungle Unity Plugin to your application. When the Import Unity Package window opens, click All to select everything before importing.

 

Target the Correct Platform in Your Build Settings

To avoid compilation errors during the next step, make sure that your project Build Settings (cmd + Shift + B) are targeting the iOS or Android platform.

Amazon Appstore

Vungle Android SDK supports Amazon OS 5.4 and higher. You can submit Android APK to the Amazon Appstore, with the additional setup of Unity Amazon Appstore configuration. Refer to the Unity instructions at the following link: https://docs.unity3d.com/Manual/UnityIAPAmazonConfiguration.html.

Google Play Services

Including Google Play Services with your project allows Vungle to provide a more customized ad experience to the end user, but it's not required. We recommend using version 11.0.1 or higher.

To include Google Play Services, we recommend Google's setup guide found on the developer portal at http://developer.android.com/google/play-services/setup.html#Setup. In your app, ensure that the device has a sufficiently updated version of Google Play Services. Vungle SDK optionally uses the location and ads API from Google Play Services.

  • android.gms:play-services-location:11.0.1
  • android.gms:play-services-ads:11.0.1
  • For play-services 7.8.0 and below: retain the support library
  • For play-services 8.4.0 and above: the support library is not required

We have successfully compiled our standalone SDK for compilation with the following versions of Google Play Services: 7.8.0, 8.4.0, 9.8.0, 10.2.4, and 11.0.1. 

After adding Google Play Services, add the following permissions to AndroidManifest.xml. Vungle uses this information to tailor the best ad experience for each user:

  • <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  • <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

 

Adding Hardware Acceleration (Android only)

Hardware acceleration is enabled by default 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 Flex native ads. Please make sure your project does not have this option set to false.

Sample code:

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

 

Step 2: Add Code

In this walkthrough we initialize all of our Vungle-related code in a script attached to the main Game Object. You can call the Vungle Unity Plugin from any scripts you think are appropriate. 

 

Initialize the SDK

Note: A default placement is created for each app automatically. You must provide its placement reference ID in this initialization step whether or not you plan to take advantage of the placements functionality. If you create multiple placements, provide all the reference IDs.

Initialize the SDK as soon as your app starts in order to give the SDK enough time to cache an ad for the auto-cached placement. To initialize the SDK, you will need:

  • all the App IDs for all platforms you need to support
  • all the Placement Reference IDs you want to use in your app for all platforms (both active and inactive)

You can find these IDs in the Vungle Dashboard (refer to "Setting Up and Reporting on Placements"). 

Sample code:

public class VungleScript : MonoBehaviour {
    string appID = "";
string iosAppID = "ios_app_id";
string androidAppID = "android_app_id";
string windowsAppID = "windows_app_id"; #if UNITY_IPHONE appID = iosAppID; Dictionary<string, bool> placements = new Dictionary<string, bool> { { "ios_placement_id_1", false }, { "ios_placement_id_2", false }, { "ios_placement_id_3", false } }; #elif UNITY_ANDROID appID = androidAppID; Dictionary<string, bool> placements = new Dictionary<string, bool> { { "android_placement_id_1", false }, { "android_placement_id_2", false }, { "android_placement_id_3", false } }; #elif UNITY_WSA_10_0 || UNITY_WINRT_8_1 || UNITY_METRO appID = windowsAppID; Dictionary<string, bool> placements = new Dictionary<string, bool> { { "windows_placement_id_1", false }, { "windows_placement_id_2", false }, { "windows_placement_id_3", false } }; #endif string[] array = new string[placements.Keys.Count]; placements.Keys.CopyTo(array, 0); Vungle.init(appID, array);
}

Once the SDK is initialized successfully, it calls the following event:

public static event Action onInitializeEvent;

Refer to the “Event Handling” section of this article.

After the Vungle SDK is initialized, it automatically requests an ad for the placement you selected as Auto Cached​ in the Vungle Dashboard. We recommend selecting the most viewed placement for auto-caching.

Once an ad is cached successfully, the adPlayableEvent event is called with the placement reference ID matching your Auto Cached​ placement. (Refer to the “Check Ad Availability for a Placement” section of this article.)

 

Load an Ad for a Placement

For placements other than the auto-cached placement, call loadAd method to load an ad.

public static void loadAd(string placementID)

Make sure that you are using the placementID that is linked to the correct platform.

Sample code:

string placementID;
#if UNITY_IPHONE
  placementID = "ios_placement_id";
#elif UNITY_ANDROID
  placementID = "android_placement_id";
#elif UNITY_WSA_10_0 || UNITY_WINRT_8_1 || UNITY_METRO
  placementID = "windows_placement_id";
#endif
  Vungle.loadAd(placementID);

 

Check Ad Availability for a Placement

Once the SDK finishes caching an ad for a placement, the following event is called:

public static event Action<string, bool> adPlayableEvent;

Sample code:

Vungle.adPlayableEvent += (placementID, adPlayable) => {
  if(placementID == "ios_placement_id") {
    playButtonPlacement1.enabled = adPlayable;
  }
};

Note:​ For the Auto Cached​ placement, this event is called only when an ad becomes available. The SDK will keep requesting an ad for the auto-cached placement. For all other placements, this event is also called in case of “Load Failed” (adPlayable returns false in this case).

You can also check the ad availability for a placement with the following method:

public static bool isAdvertAvailable(string placementID);

Play an Ad

Important: Do not play an ad until the adPlayableEvent function described above returns 'true'. If you try to play an ad before the adPlayableEvent function returns 'true', the user experience will be adversely affected while the ad tries to load. If deploying to Android, instead use the value returned from isAdvertAvailable() to ensure an ad is available (as adPlayableEvent will not return false when no ad is available).

When there is an ad available for a placement, you can play the ad with the following method:

public static void playAd(string placementID);

Sample code:

Vungle.playAd (placementID);

 

Event Handling

You can set up event handlers for all 5 Vungle SDK events surrounding ad presentation.

  • The following event is fired when the SDK starts to play a video ad. This is a great place to pause gameplay, sound effects, animations, etc.
    public static event Action onAdStartedEvent;
  • The following event is fired when the SDK closes an ad. This is a great place to reward your users and resume gameplay, sound effects, animations, etc.
    public static event Action<string, AdFinishedEventArgs> onAdFinishedEvent;

    The AdFinishedEventArgs class consists of the following properties for you to check the result of an ad play:
    public class AdFinishedEventArgs : EventArgs
    {
      //Represents a BOOL whether or not the user clicked the download button.
        public bool WasCallToActionClicked{ get; set;}
    
      //Represents a bool whether or not the video can be considered a completed view.
        public bool IsCompletedView{ get; set;}
    
    
    }
  • The following event is fired when the SDK has changed ad availability status. The isAdPlayable boolean denotes the new playability of a specific placementID.
    public static event Action<string, bool> adPlayableEvent;
    Refer to the “Check Ad Availability for a Placement” section of this article for more details.

  • The following event is fired when the SDK is initialized successfully.
    public static event Action onInitializeEvent;

Sample code:

void initializeEventHandlers() {

    Vungle.onAdStartedEvent += (placementID) => {
        DebugLog ("Ad " + placementID + " is starting!  Pause your game  animation or sound here.");
    };

    Vungle.onAdFinishedEvent += (placementID, args) => {
        DebugLog ("Ad finished - placementID " + placementID + ", was call to action clicked:" + args.WasCallToActionClicked +  ", is completed view:"
                  + args.IsCompletedView);
    };

    Vungle.adPlayableEvent += (placementID, adPlayable) => {
        DebugLog ("Ad's playable state has been changed! placementID " + placementID + ". Now: " + adPlayable);
    };

    Vungle.onInitializeEvent += () => {
        adInited = true;
        DebugLog ("SDK initialized");
    };
}

 

OnPause and OnResume Functionality

Add code for the onPause and onResume functionality that enables ads that were paused when an app was backgrounded to resume playing.

void OnApplicationPause(bool pauseStatus) {
	if (pauseStatus) {
		Vungle.onPause();
	}
	else {
		Vungle.onResume();
	}
}

 

Customization Options

The playAd method can also accept an options dictionary to customize the ad playing experience.

public static void playAd(Dictionary<string,object> options, string placementID);

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'.

The options dictionary accepts the following keys:

Key

Description

orientation

Sets the orientation of the ad. 

  • For iOS, use VungleAdOrientation:
    public enum VungleAdOrientation
    {
        Portrait = 1,
        LandscapeLeft = 2,
        LandscapeRight = 3,
        PortraitUpsideDown = 4,
        Landscape = 5,
        All = 6,
        AllButUpsideDown = 7
    }
  • For Android, set to true for matchVideo and false for autoRotate.

userTag

String of the user key that is passed to identify users in the S2S call (if there are any).

alertTitle

String that is used as the title of the alert dialog presented when a user closes an incentivized ad experience prematurely.

alertText

String that is used as the body text of the alert dialog presented when a user closes an incentivized ad experience prematurely.

closeText

String title for the close button text of the alert dialog presented when a user closes an incentivized ad experience prematurely.

continueText

String title for the close button text of the alert dialog presented when a user closes an incentivized ad experience prematurely.

immersive

Boolean which sets Immersive Mode (forces hiding the navigation bar and status bar). (Android only)

flexCloseSec

Integer determining the number of seconds after which the Flex View ad can auto-dismiss. This setting only affects Flex View ads. (iOS only)

 

GDPR: Recommended Implementation

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 Instructions" 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.

GDPR Implementation via API Instructions

To use Vungle APIs to update or query the user’s consent status as recommended in Option 1, use the Vungle.Consent enumerator and set the current value with the below two functions.

// The Consent enum is used to represent the user's current GDPR opt-in status
public enum Consent {
    Undefined = 0,
    Accepted = 1,
    Denied = 2
}

// Sets the user's consent status
void updateConsentStatus(Vungle.Consent consent);

// Gets the user's consent status
Vungle.Consent getConsentStatus();

 

Flex View Ads

For iOS

To programmatically close a Flex View ad, use the closeAd function:

Vungle.closeAd(placementID);

This function does not work on Android.

For Android

Flex View does not work the same on Unity Android as it does on Unity iOS or native Android. Because of a limitation in how Unity handles activities, Flex View does not allow a user to interact with the base game while a Flex View ad displays. In a Flex View ad, the underlying activity is suspended while an activity occurs on top. If a user leaves an app while a Flex View ad is visible and then returns to the app at a later date, the ad will still be displayed, but the background game will show up as black. This happens because the base activity is suspended until the Flex View ad is dismissed.

For this reason, avoid Flex View ads on Unity Android.

For Windows

Flex View ads are unsupported on Windows.

 

Flex Feed Ads

Flex View ads are unsupported when integrating Vungle through the Unity plugin.

Have more questions? Submit a request

Comments