Integrate Vungle SDK for Unity

Before You Begin

Requirements

Vungle Unity plugin supports Unity editor version 2017 and above and contains following Vungle SDK versions.

iOS SDK v6.8.0

  • iOS 9 or higher

Android SDK v6.8.0

  • Android 4.0 (Ice Cream Sandwich - API version 14 and higher)
  • Amazon OS 5.4 and higher
  • Requires Java 1.7 or higher for Android

Windows SDK v6.8.0

  • Windows 10 UWP and Universal 8.1

Download the Plugin

Download the Vungle plugin for Unity here: https://publisher.vungle.com/sdk/plugins/unity

Reference: Sample App

Refer to the sample app we have provided as you integrate: https://github.com/Vungle/Unity-Plugin

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, Android, or UWP 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.

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 16.0.0 or higher.

To include Google Play Services, we recommend Google's setup guide on the developer portal. In your app, make sure that the device has a sufficiently updated version of Google Play Services.

Android Dependencies

Vungle SDK for Android requires you to include one of the following dependencies in your build. Either add them manually, or include them in a Gradle template if you use Gradle.

implementation 'androidx.appcompat:appcompat:1.2.0'
// When appcompat is not used, core and localbroadcastmanager can be used instead
// implementation "androidx.core:core:1.3.1"
// implementation "androidx.localbroadcastmanager:localbroadcastmanager:1.0.0"

Add hardwareAccelerated for Android (Unity 2018.1 and below)

hardwareAccelerated is required for Vungle SDK to properly display MREC ads. Unity forces this property to be false even if it is set to true in AndroidManifest.xml inside your Unity project. Vungle plugin will set it to true using Gradle post processor script, which is available for 2018.2 and above. For pulbishers using 2018.1 and below, including 2017, must export the project to Android studio and add hardwareAccelerated configuration with a value of true.

Sample code:

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

Universial Windows Platform Project Configuration

Please follow the instruction to configure UWP project.

Preparing Vungle Unity Plugin for Windows SDK

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

Initialize the SDK as soon as your app starts in order to give the SDK enough time to cache an ad. To initialize the SDK, you will need the App IDs for the platforms you wish to support. You can find these IDs in the Vungle Dashboard (refer to "Setting Up and Reporting on Placements").

A default placement is created for each app automatically. You must provide its placement 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 placement IDs. 

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; #elif UNITY_ANDROID appID = androidAppID; #elif UNITY_WSA_10_0 || UNITY_WINRT_8_1 || UNITY_METRO appID = windowsAppID; #endif Vungle.init(appID);
}

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.

Contact your account manager about cache optimized placements to maximize caching performance.

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

Load an Ad for a Placement

For all placements, call the 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 cache optimized placements, this event is called only when an ad becomes available. Optimized placements automatically attempt to fill without further action. 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 (because the 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);

Register an Event Handler

You can set up event handlers for all five 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"); }; }

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

Banner And MREC Ads

Vungle Banner is currently in BETA phase. Please contact your account manager directly for access to ensure a successful launch.

Vungle unity plugin supports banner and MREC ads starting with v6.7.0.0. Banner ads can be set on four corners or on the middle of top, middle and bottom of the display.

You are not limited on the number of non-fullscreen ads at any given time, but the plugin does not check whether multiple ads are being displayed at one position. Please make sure that you are calling one ad for any position provided by our plugin and also ensure that they do not overlap with each other if you are displaying more than one.

VungleBannerPosition

Ad Position On Display

TopLeft

Top left corner

TopCenter

Top middle

TopRight

Top right corner

Centered

Center

BottomLeft

Bottom left corner

BottomCenter

Bottom middle

BottomRight

Bottom right corner

Vungle supports following three banner sizes and the standard MREC size.

VungleBannerSize

Dimensions

VungleAdSizeBanner

320.0f x 50.0f

VungleAdSizeBannerShort

300.0f x 50.0f

VungleAdSizeBannerLeaderboard

728.0f x 90.0f (for tablets)

VungleAdSizeBannerMedium

300.0f x 250.0f (MREC)

Load an Ad

Loading a non-fullscreen ad works differently from fullscreen ads and there is a specific loadBanner API that you use to load. You must specify the size and position of the non-fullscreen ad that you want to load and the SDK will automatically refresh it with the time interval that you configured on the dashboard. You must use placements that are specifically created for banner or MREC ads.

Load a non-fullscreen ad by calling the loadBanner method:

Vungle.loadBanner("PLACEMENT_ID", Vungle.VungleBannerSize.VungleAdSizeBanner, Vungle.VungleBannerPosition.BottomCenter);

Display an Ad

The non-fullscreen ads will be displayed at the position in the size that you specified at the time of invoking loadBanner when you call showBanner.

Vungle.showBanner("PLACEMENT_ID");

We recommend that you check for ad availibility before attempting to play any ad and isAdvertAvailable can be used just like fullscreen ads. However, for non-fullscreen ads, you would need to pass VungleBannerSize in addition to placement ID for the ad that you intend to display.

Vungle.isAdvertAvailable("PLACEMENT_ID", Vungle.VungleBannerSize.VungleAdSizeBanner);

Close an Ad

You can call closeBanner when you would like to dismiss a non-fullscreen ad.

Vungle.closeBanner("PLACEMENT_ID");

Optional and Advanced Settings

CCPA Implementation

As of July 1, 2020, California Consumer Privacy Act (CCPA) will be enforced and publishers must updated to Unity Plugin 6.7.0.0 to comply with CCPA.

Use updateCCPAStatus to set the user’s consent status to specify that the user has opted out by passing Consent.DENIED. And use getCCPAStatus to get the current CCPA status for the particular user.

public static void updateCCPAStatus(Consent consent)
public static Consent getConsentStatus()

Sample Code

Vungle.updateCCPAStatus(Vungle.Consent.Denied);
Vungle.Consent CurrentCCPAStatus = Vungle.getCCPAStatus();

Ad Configuration 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
  • UseVungleAdOrientation enum to specify desired orientation in Integer
    public enum VungleAdOrientation
    {
        Portrait = 1,
        LandscapeLeft = 2,
        LandscapeRight = 3,
        PortraitUpsideDown = 4,
        Landscape = 5,
        All = 6,
        AllButUpsideDown = 7
    }
    VungleAdOrientation Value Orientation Supported Platform
    1 Portrait iOS, Android, Windows
    2 LandscapeLeft iOS
    3 LandscapeRight iOS
    4 PortraitUpsideDown iOS
    5 Landscape iOS, Android, Windows
    6 All iOS, Android, Windows
    7 AllButUpsideDown iOS
    8 MatchVideo Android
  • For v6.7.2.1 and below, Android and Windows take true or false for orientation, which still works as of v6.8.0.0, but planned to be deprecated in the future.
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.

 

Minimum Disk Space

Minimum disk space configuration was introduced in version 6.4.0 to determine the limits for available space on a user’s device before the Vungle SDK initializes and fetch ads. Default value for SetMinimumDiskSpaceForInitialization is 51 MB and SetMinimumDiskSpaceForAd is 50 MB. The size is entered in bytes (not MB).

Vungle.SetMinimumDiskSpaceForInitialization(minValue);
Vungle.SetMinimumDiskSpaceForAd(minValue);
Vungle.init(appID);

Disable Hardware ID

For SDK version 6.4.0 onwards, publishers can now restrict from passing Hardware ID from the device to the SDK.

//Set false to opt in for Hardware ID collection by SDK or true to opt out
Vungle.EnableHardwareIdPrivacy(m_disableHardwareID);

GDPR Recommended Implementation Instructions

As of May 25, 2019, 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 sample code below 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.

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

// Sets the user's consent status and also sets a string to track GDPR version
void updateConsentStatus(Vungle.Consent consent, string consentMessageVersion);

// Gets the user's consent status
Vungle.Consent getConsentStatus();
Powered by Creativity Driven by Performance Sign Up Here

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!

Was this article helpful?