Unity Engine Integration


Updated 11/04/2017

 

Our MoPub Unity Plugin is now open source. Please access the source code here.
To access prepackaged Unity packages, please reference "Getting Started" section for further details.

Developers who have built their app on the Unity engine can easily integrate the MoPub SDK along with our custom events using our set of plugins. We support Unity 5 and above. Follow these steps:


Unity Plugin Updates

Unity Plugin 4.18

Unity Plugin 4.17

Unity Plugin 4.16.1

Unity Plugin 4.16

Unity Plugin 4.15

Unity Plugin 4.14

Unity Plugin 4.13

Unity Plugin 4.11

Unity Plugin 4.10 introduces Modularized SDK for Android

Starting in 4.10.0 release, we want to bring the modular SDK support to Android, so you choose to include specific ad formats and decrease overall SDK footprint in your app. For instance, if a publisher only wishes to integrate with MoPub’s interstitials and rewarded videos, you no longer need to include the banner SDK module to your project. For taking advantage of the new modular features, download the Android Unity package 4.10 from the "Getting Started" section and choose the modules of your choice from Assets/Plugins/Android/mopub/libs/ directory:

Note: interstitials is a prerequisite for rewarded videos, so one cannot integrate with rewarded videos without the interstitials SDK module.

Unity Plugin 4.9 comes with two major updates:

Please note that there is no backward compatibility with SDK versions earlier than 4.9. For earlier versions, please check our reference documentation.


Getting Started

    1. Download the latest plugin here.
    2. Import the MoPubUnityPlugin.unitypackage file into your Unity project. Select MoPubPlugin.unitypackage along with the pre-built adaptors you wish and double-click (available for AdColony, AdMob, Chartboost, Facebook Audience Network, Millennial Media, UnityAds, and Vungle).
    3. Switch back to Unity. Upon importing MoPubUnityPlugin.unitypackage, you will see several modular jars of the new modular Android SDK for all versions 4.9.0 and newer:
      • Assets/Plugins/Android/mopub/libs/mopub-sdk.jar
      • Assets/Plugins/Android/mopub/libs/mopub-sdk-base.jar
      • Assets/Plugins/Android/mopub/libs/mopub-sdk-banner.jar
      • Assets/Plugins/Android/mopub/libs/mopub-sdk-interstitial.jar
      • Assets/Plugins/Android/mopub/libs/mopub-sdk-rewardedvideo.jar

      All mopub-sdk-* jars are required.

    4. Keep all files selected in the ‘Importing Package’ window and click Import.
    5. For the third-party networks, one also needs to place the network SDKs into the /Assets/Editor folder within one’s Unity project.
      • For iOS, the path is: [UNITY PROJECT ROOT]/Assets/MoPub/Editor/Support/[NETWORK]/[NETWORK SDK]
      • For Android, the path is: [UNITY PROJECT ROOT]/Assets/Plugins/Android/
      • Note: You will need to include Google Play Services in the above locations as well. 
    6. Instantiate the plugin. With plugin version 4.9.0 and newer, there is support for multiple plugin instances: one per banner, interstitial, or rewarded video adunit. This new feature allows the publisher to precache multiple banner, interstitial, and rewarded video adunits and load them in any order later. To instantiate a plugin for each adunit, you have to pass in a string array of adunit IDs to method loadPluginsForAdUnitsin the MoPubDemoGUI.cs file:
MoPub.loadPluginsForAdUnits (arrayOfAdUnits);

All banner, interstitial, and rewarded video API calls in MoPub.cs require the adunit ID as a parameter, since the adunit ID is being used to retrieve the corresponding Unity plugin. 6. Choose the format you’d like to integrate and follow the instructions below for your format.


Integrating Banners

Banner ads usually appear at the top or bottom of your app’s screen. Adding one to your app takes just a few lines of code. Here is how you would create a banner in the Unity Script file - make sure you only call this once in the lifecycle of your app: Make sure your script is “using System”.

    1. Create a banner:
MoPub.createBanner (bannerAdUnit, MoPubAdPosition.BottomRight);
    1. Show/hide the banner (optional - the banner is shown by default):
MoPub.showBanner (bannerAdUnit, true);
MoPub.showBanner (bannerAdUnit, false);  // hides the banner
    1. Destroy the banner:
MoPub.destroyBanner (bannerAdUnit);
MoPub.destroyBanner (bannerAdUnit);

If your game is distributed on iOS and Android, you only need to import the plugin only once, but you need to create different ad units per OS:

#if UNITY_IOS
MoPub.createBanner("REPLACE_BY_IPHONE_AD_UNIT_ID_HERE", MoPubAdPosition.BottomCenter );
#elif
UNITY_ANDROID MoPub.createBanner("REPLACE_BY_ANDROID_AD_UNIT_ID_HERE", MoPubAdPosition.BottomCenter );
#endif

Here are the banner-related callback handlers:

void onAdLoaded (string height)
void onAdFailed (string errorMsg)
void onAdClicked (string adUnitId)
void onAdExpanded (string adUnitId)
void onAdCollapsed (string adUnitId)

 

Banner Best Practices


Integrating Interstitials

Interstitial ads provide full-screen experiences, commonly incorporating rich media to offer a higher level of interactivity than banner ads. Interstitials are typically shown during natural transitions in your application, such as on app launch, after completing a game level, or while your app is downloading content from the internet.

    1. Pre-fetch an interstitial:
MoPub.requestInterstitialAd(interstitialAdUnit);
    1. Show the interstitial:
MoPub.showInterstitialAd (interstitialAdUnit);
    1. [Optional] Implement the lifecycle callbacks:

The MoPub Unity plugin includes a variety of optional callbacks that you can use to be notified of events, e.g. when an interstitial has successfully loaded, or when an interstitial is closed. Here are the interstitial-related callback handlers:

void onInterstitialLoaded (string adUnitId)
void onInterstitialFailed (string errorMsg)
void onInterstitialDismissed (string adUnitId)
void interstitialDidExpire (string adUnitId)
void onInterstitialShown (string adUnitId)
void onInterstitialClicked (string adUnitId)

 

Interstitial Best Practices


Integrating Rewarded Video

Rewarded video ads are a great way to offer users an incentive to stay engaged in your app, while earning more ad revenue. The reward generally comes in the form of in-game currency (gold, coins, power-ups) and is distributed to the user after a successful video completion. MoPub’s mediation solution officially supports rewarded videos from popular ad networks like AdColony, Unity Ads, Vungle, Chartboost and Tapjoy.

    1. Initialize rewarded video:
MoPub.initializeRewardedVideo();
    1. Pre-fetch the rewarded video ad:
MoPub.requestRewardedVideo(rewardedVideoAdUnit, mediationSettings, keywords, latitude, longitude, customerId);
    1. Show the rewarded video:
MoPub.showRewardedVideo(rewardedVideoAdUnit);
    1. [Optional] Implement the lifecycle callbacks:

Here are the rewarded video-related callback handlers:

void onRewardedVideoLoaded (string adUnitId)
void onRewardedVideoFailed (string errorMsg)
void onRewardedVideoExpired (string adUnitId)
void onRewardedVideoShown (string adUnitId)
void onRewardedVideoFailedToPlay (string adUnitId)
void onRewardedVideoReceivedReward (string json)
void onRewardedVideoClosed (string adUnitId)
void onRewardedVideoLeavingApplication (string adUnitId)

 

Rewarded Video Best Practices


Network Mediation Settings

Mediation settings enable you to pass in third-party network specific settings and can be provided as additional parameters during the rewarded video initialization call.

    1. Implement getMediationSettings()as below for both iOS and Android to return a list of settings. The keys in the key-value pairs should be as per the keys defined by each network.
// Set up mediation settings. Mediation settings vary based on platform so we use a simple helper  method to generate them here: 

#if UNITY_IOS  

List getMediationSettings()

{
  var adColonySettings = new MoPubMediationSetting (“AdColony”);
  adColonySettings.Add (“showPrePopup”, false);
  adColonySettings.Add (“showPostPopup”, true);

  var vungleSettings = new MoPubMediationSetting (“Vungle”);
  vungleSettings.Add (“userIdentifier”, “the-user-id”);

  var mediationSettings = new List ();

  mediationSettings.Add (adColonySettings);
  mediationSettings.Add (vungleSettings);

  return mediationSettings;
}

#elif UNITY_ANDROID

List getMediationSettings()

{
  var adColonySettings = new MoPubMediationSetting (“AdColony”);
  adColonySettings.Add (“withConfirmationDialog”, false);
  adColonySettings.Add (“withResultsDialog”, true);

  var chartboostSettings = new MoPubMediationSetting (“Chartboost”);
  chartboostSettings.Add (“customId”, “the-user-id”);

  var vungleSettings = new MoPubMediationSetting (“Vungle”);
  vungleSettings.Add (“userId”, “the-user-id”);
  vungleSettings.Add (“cancelDialogBody”, “Cancel Body”);
  vungleSettings.Add (“cancelDialogCloseButton”, “Shut it Down”);\
  vungleSettings.Add (“cancelDialogKeepWatchingButton”, “Watch On”);
  vungleSettings.Add (“cancelDialogTitle”, “Cancel Title”);

  var mediationSettings = new List ();
  mediationSettings.Add (adColonySettings);
  mediationSettings.Add (chartboostSettings);
  mediationSettings.Add (vungleSettings);

  return mediationSettings;
}

#endif
  1. Initialize Third-Party SDKs: Please refer to the ad network’s documentation to initialize the SDK within your Activity on Android and AppDelegate.m file on iOS.

Note: For mediating AdColony through MoPub's unity wrappers, do add Unity-specific AdColony JARs to receive ads from AdColony SDK.


Writing Custom Events for Unsupported Ad Networks

Android
  1. Follow this guide to author the custom event class for Android
  2. Add the custom event adapters with their corresponding network SDKs as additional library jars to the existing libraries into the [UNITY PROJECT ROOT]/Assets/Plugins/Android folder. For ease of maintenance, we recommend keeping the custom event classes and the network SDKs as separate .jar files.
iOS
  1. Follow this guide to author the custom event class for iOS
  2. Create a separate folder in [UNITY PROJECT ROOT]/Assets/Editor/MoPub/NativeCode and add the SDKs and custom event files directly

Troubleshooting


Known Limitations


Extras

Here’s how to report a conversion/app open event:

MoPub.reportApplicationOpen("iTunesAppID");

Here’s how to enable/disable location passing:

MoPub.enableLocationSupport(true);
MoPub.enableLocationSupport(false);

 

Updated: November 2017