Get Started with Vungle (SDK v.1.0 - v.4.1) - 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 Apple iOS 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 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 and Placement IDs, they can be found in the Vungle Dashboard on your apps' pages
Vungle.init ("Test_Android", "Test_iOS", "vungleTest");

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.

 

 

Play an Ad

You can play the ad with the following method:

       Vungle.playAd();

 

Customization Options

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

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

The options dictionary accepts the following keys:

Key Description
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).
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.

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

You can set up EventHandlers 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<string> 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 time in seconds that the user watched the video.

       public double TimeWatched{ 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;



●  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<string> onLogEvent;

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 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, download our Unity Sample app.  Create a new project in Unity.  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.

In Project window, navigate to the Assets Folder, check to see if this folder has all the files in your downloaded project Assets folder, highlighted in Red below.  If all these files are not in your Unity Assets folder then move them manually by right clicking on Assets folder in Unity and choose "open in finder", in the opened finder window copy and paste everything from the downloaded Sample app assets folder to your Unity project's Asset folder and replace the files if necessary.

Screen_Shot_2017-06-27_at_5.43.12_PM.png

In Unity, project navigator->Assets doubleclick on MainTitleScreen:

Screen_Shot_2017-06-27_at_6.01.39_PM.png

Click on GameObject, choose TitleGUI inside Inspector->Title GUI (Script):

Screen_Shot_2017-06-27_at_6.02.57_PM.png

Press Command + Shift + B to open up Build Settings.  Click on iOS or Android then hit Switch Platform.

Screen_Shot_2017-06-27_at_6.14.34_PM.png

In the Build Settings window click on Player Settings.  In Inspector, make sure values below in red are unique to your app:

Screen_Shot_2017-06-27_at_6.16.56_PM.png

Now go back to Build Settings and click "Build" to generate a Android apk file or a Xcode project.

 

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