1. Help Center
  2. Vungle SDK
  3. Unity Plugin

Integrate Vungle SDK for Unity

Avatar
John Mai
Follow

Before You Begin

Requirements

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

  • iOS SDK v6.11.0
    • iOS 10 or higher
    • Xcode 12.4 or higher
    • For apps using Xcode 13, using Vungle SDK 6.10.3+ is required as older SDKs do not support Xcode 13 for iOS 15 devices.
  • Android SDK v6.11.0
    • Android 5.0 (API version 21) and higher
    • Amazon OS 5.4 and higher
    • Requires Java 1.8 or higher for Android
  • Windows SDK v6.11.0
    • Universal Windows Platform (UWP)
    • As of Vungle Windows SDK v6.11, Vungle supports ARM64. This requires you to set your minimum target version in Microsoft Project to Windows 10.0 build 16299 (also known as the Fall Creators Update, or version 1709). To do this in Build Settings, under Platform select Universal Windows Platform, and set Minimum Platform Version to ‘10.0.16299.0’ as shown below.
      Note that this is required for all publishers, even those unaffected by ARM64.
      unity-windows-setting.jpg

Download the Plugin

Download the Vungle plugin for 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, import the downloaded VunglePlugin.unitypackage file by Assets > Import Package > Custom Package. When the Import Unity Package window opens, click All to select everything before Import.

If you have imported the plugin before, we recommend that you remove the previous plugin libraries and files to avoid conflict.

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 Universal Windows platform.

iOS

Add SKAdNetworkIDs to Info.plist

Configure your app to participate in ad campaigns via the SKAdNetwork framework on iOS 14+. To do this, add the list of our approved partner IDs for advertising attribution to your Info.plist file. Adding the Vungle SKAdNetwork ID and the IDs of all the DSPs to whom you want to sell indicates that your app wants to work with Vungle and accept bids from these buyers.

Follow the steps below to configure your app with SKAdNetworkIDs. Refer to Apple’s documentation on configuring the Info.plist properly for ad campaigns to be served. Refer also to the Xcode documentation for help on editing property lists.

The Unity package will automatically add the SKAdNetworkIDs into the Info.plist using the post-processing script, VungleiOSBuildHelper.cs. The SKAdNetworkIDs added can be viewed inside the array string[] SKAdNetwork in the script.

To set the SKAdNetworkIDs list manually in Xcode:

  1. Inside the Xcode Project navigator, open the Info.plist file.
  2. Click the add button (+) next to a key in a property list inside the Info.plist file to create a new property key.
  3. Enter SKAdNetworkItems and select Array in the Type column.
  4. Add a dictionary item, then add a single String item inside the dictionary.
  5. For each String item, add SKAdNetworkIdentifier as the key and the ad network identifier as the value.

Vungle hosts the Vungle SKAdNetwork ID and the list of our buyers' SKAdNetwork IDs in both JSON and XML formats on our website. Note that our lists are updated periodically:

AppTrackingTransparency

Apple has introduced the ATT framework in iOS 14. This framework is not required for our plugin; however, if you plan to use this framework, complete the following steps.

Attach a handler to Vungle.onAppTrackingEvent and receive a callback when the prompt is complete. To trigger the prompt use: Vungle.RequestTrackingAuthorization(). The prompt shows the string message from the plist variable NSUserTrackingUsageDescription inside Vungle/Editor/VungleiOSBuildHelper.cs.

If you do not plan to trigger the prompt, do not add the plist variable. Remove rootDict.SetString("NSUserTrackingUsageDescription", NSUserTrackingUsageDescription); in the method PostProcessIosBuild found in the class VungleiOSBuildHelper.cs.

For Unity 2018 and Lower: Change Shared Project Build Setting to New Build System

When using Unity 2018 and below, please ensure that the Shared Project Build Setting is set to New Build System. Refer to the Unity 2018 and Lower: Legacy Build System Error documentation

Android or Amazon

COPPA Compliance

Starting with Unity Plugin v.6.10.6.2, Vungle provides an optional method for you to indicate to the Vungle SDK at the device level whether the user within the given mobile app is under or over the age of 13. 

To implement COPPA:

  1. Refer to our COPPA Implementation details for Android.
  2. To beta-test the COPPA API, please contact Liftoff Support at tech-support@vungle.com.

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"

For Unity 2018.1 and Lower on Android, Add hardwareAccelerated 

hardwareAccelerated is required for Vungle SDK to properly display banner ads. However, Unity forces this property to be false, even when it is set to 'true' in AndroidManifest.xml file inside your Unity project. To correct this, the Vungle plugin sets it to 'true' using the Gradle post processor script, but this functionality is only available for Unity 2018.2 and higher. Therefore, if you are using Unity 2018.1 or lower (including Unity 2017), you must do this manually by exporting the project to Android Studio and adding the hardwareAccelerated configuration with a value of 'true'.

Sample code:

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

Windows

Update Build and Project Settings

  1. Open Build Settings (Ctrl + Shift + B).
  2. Under Platform, select Universal Windows Platform.
  3. Make sure Build Type is set to "XAML Project" because the Vungle Unity plugin does not support the D3D project build type.
  4. Open Player Settings, and then Publishing Settings.
  5. Make sure internetClient permission is granted in the Capabilities menu.

unity1.png

For Vungle Unity Plugin Versions Lower Than 6.7 Only: Configure Your Universal Windows Platform Project

The steps in this section are not required for Vungle Unity Plugin v6.7.x and higher.

Under the Project tab are two VungleSDKProxy items. Under the Inspector tab, confirm that the following parameters are set correctly in the Select platforms for plugin and Platform settings sections:

Assets/Plugins/VungleSDKProxy.dll:

unity2.png
  • General
    • Auto Reference should be checked
    • Validate References should be checked
  • Select platforms for plugin
    • Editor should be checked
  • Platform settings
    • CPU: Select Any CPU
    • OS: Select Any OS

Assets/Plugins/metro/VungleSDKProxy.winmd:

unity3.png
  • Select platforms for plugin
    • WSAPlayer should be checked
  • Platform settings
    • SDK: Select Any SDK
    • ScriptingBackend: Select Any Scripting Backend

Supported Scripting Backend

Vungle Unity Plugin v6.5.2.1 and higher supports IL2CPP scripting backend, but it is limited to Unity 2018 and higher due to limitations on the Unity side. For Unity 2017, use the .NET scripting backend instead.

Unity Version Supported Scripting Backend
2017 .NET
2018 .NET, IL2CPP
2019+ IL2CPP

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 that are appropriate.

Initialize the SDK

Initialize the SDK as soon as your app starts to give the SDK enough time to cache an ad. To initialize the SDK, you must have the App IDs for the platforms you wish to support. You can find these IDs in the Liftoff Monetize 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 the ad format article of your choice.

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 ad format article of your choice for more detail.

Integrate Ad Formats

Complete your plugin integration for each ad format that you plan to display in your app. Refer to our instructions for each ad format:

Further Customize Your Ads

Follow the instructions in our Advanced Settings article to fine-tune your app's integration with additional configuration options, such as GDPR, CCPA implementation, and many other settings.

In Vungle Unity SDK v.6.9.1 for both Android/Amazon and iOS, we introduced the ability to offset banner ads with this new API: Vungle.setBannerOffset(placementID, x, y). The setBannerOffset should happen after the load and can be done after the banner is displayed. Positive X will move the banner to the right. Negative X will move the banner to the left. Positive Y will move the banner down. Negative Y will move the banner up. Note that the distance of the offset may be different across all platforms and is dependent on how the OS handles the offset.

Sample code: 

void onPlayBanner1()
{
    Vungle.showBanner(<banner_placementID here>);
    Vungle.setBannerOffset(<banner_placementID here>, 50, 50);
}

In Vungle Unity Plugin v.6.9.1 for both iOS and Android/Amazon, the Unity plugin also includes Vungle.isSoundEnabled API to check the value of Vungle.setSoundEnabled.

Sample code: 

//The default value of Vungle.isSoundEnabled() is true

Vungle.setSoundEnabled(false);
DebugLog("Is sound enabled:" + Vungle.isSoundEnabled()); //Vungle.isSoundEnabled should return false

Vungle.setSoundEnabled(true);
DebugLog("Is sound enabled:" + Vungle.isSoundEnabled()); //Vungle.isSoundEnabled should return true.

Questions?

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

Submit a request
Was this article helpful?