Get Started with Vungle - Unity

This guide covers the quick integration of our Vungle Unity Plugin into a basic sample application. The source code referenced here is available on our public GitHub repository.

Contents

  1. Before you get started
  2. Install the Vungle Unity Plugin
  3. Add the code!
  4. Running the Vungle sample app
  5. How to export an Xcode project on Windows

Before you get started...

    1. The Vungle Unity Plugin requires Java 1.7 for Android and supports iOS 7+.

      IMPORTANT - There is a bug in Unity 5.3 and 5.3.1 preventing Unity from building apps for Windows 8.1. Unity has released a patch resolving this issue and we recommend using the following versions: 5.3.1p1, 5.3.1p2, and 5.3.1p3. DO NOT USE UNITY VERSIONS 5.3 OR 5.3.1!

    2. The Vungle Unity Plugin:
      - for Vungle iOS SDK 4.0.6 supports Unity 4 and Unity 5.4.1 or higher.
      - for Android supports both Unity 5 and Unity 4. 
      - for Windows (Universal 8.1 or Phone 8.1) supports Unity 4 and higher.
      - for Windows (Windows 10 UWP) supports Unity 5.2 and higher. 

    3. For Windows, install the Windows SDK before following the rest of these instructions to install the Vungle Unity Plugin. Windows development can only be performed on a Windows PC. Make sure you have the Windows SDK installed for the platform version you are using in development:

      - Download Windows SDK 8.1 - https://developer.microsoft.com/en-us/windows/downloads/windows-8-1-sdk

      - Download Windows SDK 10 - https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk

    4. Vungle ads on Windows N and KN Edition: For users with special N or KN edition of Windows, "Media feature pack for Windows 10 N and KN Editions" must be installed for Vungle ads to work.

    5. The integration requires a Vungle account, so create a Vungle account if you don't have one.

    6. If you haven't already done so, head over to our dashboard and add your app to your account. You need to do this so that you can get your App ID, which you’ll be adding to your app with our SDK. For example, in the image below, the App ID is circled in redand can be found on your app’s page.

      In newer applications, the Application ID may match the Reporting API ID. For existing applications created using 'search', the Application ID and Reporting API ID may differ. (For mediation, the Reporting API 'key' is found on the User account details page.) 

The Vungle Unity Plugin is not included in the sample code linked above, so make sure you've downloaded it first from the Vungle dashboard.  Once the download's complete...

Install the Vungle Unity Plugin

With Unity open and your project presented, double-click the downloaded VunglePlugin.unitypackage file to add the Vungle Unity Plugin to your application.

Click All to select everything before importing.

Ensure you're targeting 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, Android, or Windows platform.

For Windows

If you are using Unity 5 for Windows, our SDK has a separate VungleSDK.winmd file for each Windows platform. The files are in directories named after the corresponding platform. Referring to the following image, complete the following settings:

Under the Project tab, select the appropriate Vungle SDK. Confirm that the following parameters under the Inspector tab, in the Select platforms for plugin and Platform settings sections are properly set:

  • For Assets/Plugins/metro/VungleSDKProxy.winmd:
    Platform: WSAPlayer
    SDK: Any SDK
    Placeholder: Assets/Plugins/VungleSDKProxy.dll:

  • For Assets/Plugins/metro/VungleSDK.winmd:
    Platform: WSAPlayer
    SDK: SDK81

  • For Assets/Plugins/metro/UWP/VungleSDK.winmd:
    Platform: WSAPlayer
    SDK: UWP

  • For Assets/Plugins/metro/WindowsPhone81/VungleSDK.winmd:
    Platform: WSAPlayer
    SDK: Phone SDK81

Important! If you are using Unity version 5.3.1 or higher to build the Universal 8.1 or Phone 8.1 project, you must disable the use of Assets/Plugins/metro/UWP/VungleSDK.winmd in one of these two ways:

  • Either select Assets/Plugins/metro/UWP/VungleSDK.winmd and, under the Inspector tab, in the Select platforms for plugin section, clear the WSAPlayer option
  • Or delete Assets/Plugins/metro/UWP/VungleSDK.winmd

If you are using Unity 4, go to Player settings --> Publishing Settings and change the following settings:

  • Unprocessed Plugins: Size 1
  • Element 0: VungleSDKProxy.dll

After you publish the Windows project in Unity, make sure that your project has the internetClient capability in Unity environment. Open Build Settings (shift + ctrl + b) --> Select Windows Store under Platform --> click Player Settings. Under Publishing Settings, in the Capabilities menu, select the InternetClient option, as shown:

Add the code!

In this walkthrough we're going to initialize all of our Vungle-related code in a script attached to the main Game Object, but feel free to call the Vungle Unity Plugin from any scripts you feel appropriate.  It's best to initialize the Vungle Unity Plugin as soon as possible, however, to ensure that the included Vungle SDKs have completed configuration in time to present an ad to the user when 'playAd' is called.

Initialize

Initialization is just one line. It only needs to be called once, and is used to prepare the Vungle Unity Plugin to present ads to the user  *Try to initialize the Vungle SDK as early as possible in your application, because the SDK needs 30-45 seconds to initialize and cache an ad for playback*:

//Your App IDs can be found in the Vungle Dashboard on your apps' pages
Vungle.init ("Test_Android", "Test_iOS", "Test_Windows");

Playing Ads

Playing an ad is another one-liner.

//Short and simple!
Vungle.playAd();

The playAd method can also accept an options dictionary to customize the ad play experience:

// Plays an ad with more options. Use Dictionary<string,object> to set options.
public static void playAdWithOptions( Dictionary<string,object> options );

The options dictionary accepts the following keys:

Key Description
incentivized

You can choose to be notified whenever a user has completed an ad. A typical use case of this is when you are offering some sort of value exchange (‘watch this video and receive 100 gems!’). If you choose to make your ads incentivized, we’ll immediately send a message to your server along with a user id (that you provide) so that you can reward your users. By setting to "true" for this, an ad will be incentivized. Refer to our instructions for setting up incentivized ads.

Dictionary<string, object> options = new Dictionary<string, object> ();
options ["incentivized"] = true;
Vungle.playAdWithOptions (options);
orientation

Sets the orientation of the ad.

  • For iOS, please 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.
  • For Windows, set to true for autoRotate and false for landscape. (The default is autoRotate.)
userTag The key user is the one passed as user in the S2S call (if there are any).
placement Metadata noting the placement detail of an individual ad play.  This is used to filter different ad experiences when retrieving report data for your application's performance.
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

Immersive mode

key1..8 We have 8 keys built in here

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

Event Handling

The Vungle Unity Plugin allows an app to subscribe to 4 events surrounding ad presentation:

// Fired when a Vungle ad is ready to be displayed
public static event Action<bool> adPlayableEvent;
// Fired when a Vungle ad starts
public static event Action onAdStartedEvent;
//Fired when a Vungle ad finishes and provides the entire information about this event
public static event Action<AdFinishedEventArgs> onAdFinishedEvent; 

The AdFinishedEventArgs class consists of following parameters.

public class AdFinishedEventArgs : EventArgs
{
	// true if a user tapped Download button to go store
	public bool WasCallToActionClicked;

	// true if at least 80% of the video was watched
	public bool IsCompletedView;

	// duration a Vungle ad watched
	public double TimeWatched;

	// total duration of a Vungle ad
	public double TotalDuration;
}
// Fired when the SDK sends a log event
public static event Action<string> onLogEvent;

Note: The following three events are deprecated:

// DEPRECATED: Please use adPlayableEvent event instead.
public static event Action onCachedAdAvailableEvent;

// DEPRECATED: Please use onAdFinishedEvent event instead.
public static event Action onAdEndedEvent;
	
// DEPRECATED: Please use onAdFinishedEvent event instead.
public static event Action<double,double> onAdViewedEvent;

Subscribing to these events is easy, and is done through the VungleManager object. In C#, adding an event listener would look like this:

// Encapsulated functionality called asynchronously each time event is triggered
Vungle.adPlayableEvent += (isAdAvailable) => {
	if (isAdAvailable) {
DebugLog ("An ad is ready to show!");
} else {
DebugLog ("No ad is available at this moment.");
} };

And that's it! For more information about Vungle Unity plugins check out our other plugin articles, or look through the source code for our Unity Sample app.

 

Note on plugin import: On import, you may see errors similar to:

Could not create texture from Assets/Editor/Vungle/VungleSDK/vg_privacy.png: 
File could not be read

appear in the Unity Console.  These only occur during the initial import of the plugin, and can be safely Cleared (the Clear button is on the top left of the Unity Console). The errors will not affect build or export, and are only temporarily encountered during the import process!

Note on testing your app in Test mode: While your app is in Test mode, you will not be able to download any of the apps advertised. Additionally, the Dashboard will not report the number of impressions. This is because test ads are used only to verify that you have integrated the SDK correctly. This functionality becomes available once your app has gone live in active mode.

Running the Vungle sample app

To run our sample app, navigate to the Assets -->Plugins --> Vungle --> demo folder and double-click VungleCombo.unity to load the app. Ensure that VungleCombo is shown under Hierarchy window, then click Build and Run.

How to export an Xcode project on Windows

To export an Xcode project from Unity on a Windows machine, you must have the Python programming language installed on your machine. Whether you are only installing Python for this purpose or experiencing a problem at export, install the latest version of Python from here: https://www.python.org/.

 

Have more questions? Submit a request

Comments