Unity Engine Integration

Introduction

Unity developers can easily integrate the MoPub SDK along with our mediation adapters via Unity packages. We support Unity 5.5 and above.

What’s new in 5.0

Publishers upgrading to the 5.0 MoPub SDK are required to take additional steps. Reference our guides for SDK Initialization and GDPR for more details on how to stay up-to-date and compliant.

Migrating to 5.4

The 5.4 release of the MoPub Unity plugin internally reorganizes the directory/file structure (see below for the detailed breakdown). For publishers upgrading to this version, the plugin automatically detects if there are legacy directories/files in the existing project. Simply navigate to the MoPub menu, and you should see a “Migrate” button if your project needs a cleanup.

NOTE: Performing the migration is optional as it simply moves all MoPub code to the same directory. Whether or not the operation is triggered does not have any adverse effect on the project or integration.

NOTE: The migration operation is irreversible. Ensure you have backed up your project before launching the migration task.

Unity Native

Unity Native

Unity Native

The following files and directories are automatically migrated by the migration task:

Legacy Location New Location
MoPub/Extras/ DELETED (redundant content)
MoPub/Editor MoPub/Scripts/Editor
MoPub/Internal MoPub/Scripts/Internal
MoPub/ThirdParty MoPub/Scripts/ThirdParty
MoPub/MoPub.cs MoPub/Scripts/MoPub.cs
MoPub/MoPubManager.cs MoPub/Scripts/MoPubManager.cs
MoPub/mopub-dark-logo.png MoPub/Sample/mopub-dark-logo.png
Scenes/MoPubDemoScene.unity MoPub/Sample/MoPubDemoScene.unity
Scripts/GravityController.cs MoPub/Sample/GravityController.cs
Scripts/MoPubDemoGUI.cs MoPub/Sample/MoPubDemoGUI.cs
Scripts/MoPubEventListener.cs MoPub/Sample/MoPubEventListener.cs
Plugins/Android/README.txt MoPub/Plugins/Android/MoPub.plugin/README.txt
Plugins/Android/mopub MoPub/Plugins/Android/MoPub.plugin
Plugins/iOS/MoPubBinding.m MoPub/Plugins/iOS/MoPubBinding.m
Plugins/iOS/MoPubManager.h MoPub/Plugins/iOS/MoPubManager.h
Plugins/iOS/MoPubManager.mm MoPub/Plugins/iOS/MoPubManager.mm
Plugins/iOS/MoPubSDKFramework.framework MoPub/Plugins/iOS/MoPubSDKFramework.framework

The files under unity-sample-app/Assets cannot be automatically migrated, so should be reviewed and migrated manually if desired. If publishers have not modified them so they’re still just MoPub code, these files can be moved to the new location:

Legacy Location New Location
Plugins/Android/res/drawable/ic_launcher_foreground.png MoPub/Plugins/Android/MoPub.plugin/res/drawable/
Plugins/Android/res/drawable-anydpi-v26/app_icon.xml MoPub/Plugins/Android/MoPub.plugin/res/drawable-anydpi-v26/
Plugins/Android/res/values/ic_launcher_background.xml MoPub/Plugins/Android/MoPub.plugin/res/values/

Unity Native

Exception: The files under the following directories are currently not handled by the migration task. They are subject to change in a future Unity plugin release:

Legacy Location New Location
Plugins/Android/mopub-support/* MoPub/Plugins/Android/MoPub.plugin/

Integrate the Plugin and Adapters

  1. Download the latest MoPub Unity plugin here.

  2. If you would like to use mediation, download the mediation adapters here.

  3. To import the MoPub Unity plugin, double-click on the MoPubUnityPlugin.unitypackage, or go to Assets > Import Package > Custom Package.

  4. Upon importing MoPubUnity.unitypackage, keep all files selected in the Importing Package window and click Import.

  5. To import the mediation adapters, double-click on the corresponding network .unitypackage or go to Assets > Import Package > Custom Package. Take AdMob for example:

  6. To mediate third-party ad networks, download the certified network SDKs from the link in the MoPub Mediation Integration Tool > Your Network Name > Learn More. Please make sure you are using the cerified version.

    Note: Some networks might also provide a Unity version of their SDK. For AdColony, you need to use its Unity SDK specifically. For other networks, make sure to always download their native Android and iOS SDKs instead in this integration.

  7. Place the network SDKs in your Unity project according to the file extensions, like so:

    SDK File Type Path to place the network SDKs Note
    Android (.aar) [UNITY PROJECT ROOT]/Assets/Plugins/Android If required by networks, add Google Play services aars to this directory
    Android (.jar) [UNITY PROJECT ROOT]/Assets/Plugins/Android/mopub-support/libs If required by networks, add Google Play services jars to this directory.
    iOS (.framework) [UNITY PROJECT ROOT]/Assets/Plugins/iOS Manually add frameworks to your project in Xcode if needed †
  8. Before you build your app project, for Android, make sure to add required <Activity> for specific networks if needed (to the AndroidManifest.xml). Please check out the networks’ Android integration guide for details.

  9. Build and run your Unity project. For iOS, after exporting your project into Xcode, ensure MoPubSDKFramework.framework is in the Embedded Binaries list. Otherwise click the + button to add it.

    XCode EB

  10. Ensure the MoPubSDKFramework.framework and other network frameworks are in the Linked Frameworks and Libraries list. Otherwise, click the + button to add them.

    Note: For publishers using MoPub plugin version 5.0+ and Unity version below 2017.1 on iOS, make sure to update to MoPub plugin version 5.0.1 or higher, and review the above steps.

Getting Started with Ads

  1. Follow this instruction to initialize the SDK.

  2. Instantiate the plugin for each ad format. You have to pass in a String array of adunit IDs to the methods as shown in below:

     MoPub.LoadBannerPluginsForAdUnits(_bannerAdUnits);
     MoPub.LoadInterstitialPluginsForAdUnits(_interstitialAdUnits);
     MoPub.LoadRewardedVideoPluginsForAdUnits(_rewardedVideoAdUnits);
     MoPub.LoadRewardedVideoPluginsForAdUnits(_rewardedRichMediaAdUnits);
    
  3. Choose the format you’d like to integrate and follow the instructions for each format:

Additionally, check out this page for other instructions of mediation integration.

Conversion Tracking

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

Known Limitations

  • Plugins for the Unity engine do not mediate native ad formats.
  • Developers should test to verify compatibility with other third party plugins.

Last updated October 10, 2018

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2018 MoPub Inc.