Get Started with Vungle SDK v. 5 - 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: https://github.com/Vungle/Unity-Plugin/tree/sdk5.

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

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

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 == ) {
    layButtonPlacement1.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 ‘NO’ 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

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 ();

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

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

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.onLogEvent += (log) => {
            DebugLog ("Log: " + log);
        };

        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

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

Turn on Immersive mode for Android.

 

Have more questions? Submit a request

Comments