Integrate the MoPub SDK for Unity

New: Check out the Integration Suite for a faster way to integrate the MoPub SDK.

Use these instructions to integrate the MoPub SDK with your Unity app. If you have already integrated our Unity plugin and are upgrading to a higher version, follow our migrating instructions.

High-Level Steps to Integrate

MoPub supports Unity editor version 2018.4 (LTS) and above. In general, the minimum supported Unity version will be the Long Term Support version from 2 years prior.

  1. Integrate the MoPub Unity plugin and mediation adapters.
  2. Initialize the SDK.
  3. Configure ad units in your app.

Step 1. Integrate the Plugin and Mediation Adapters

There are two ways to integrate:

  1. The best option is using the SDK Manager and is the recommended method.
  2. However, we also provide instructions for integrating the plugin and adapters manually.

Starting with v. 5.5.0 of the MoPub Unity Plugin, we include the External Dependency Manager (formerly Play Services Resolver/Jar Resolver) for dependency resolution. Read more about the External Dependency Manager tool below.

Refer to the release notes for the compatible External Dependency Manager version the MoPub Unity Plugin supports.

Regardless of the integration option you take, ensure the necessary third-party dependencies outlined in the respective Android and iOS sections of our documentation are included in your Unity project. Missing libraries can result in unexpected app and SDK behaviors.

We strongly recommend using the SDK Manager (download it here), which we introduced with our 5.5.0 release of the MoPub Unity plugin. Use this new interface to automatically download and install the correct versions of the MoPub SDK, the mediation SDKs, and the associated mediation adapters. The SDK Manager also detects your currently installed versions and prompts you to update any outdated SDKs and adapters.

SDK Manager

We support mediation SDKs that are distributed on Maven Central and CocoaPods. For SDKs that are only available via direct download from the ad network’s homepage (indicated by [?] buttons in the SDK Manager), you will continue to integrate them manually. The SDK Manager lets you download the .unitypackage archive that has the adapters. All you need to do is download and place the corresponding mediation SDKs in Assets/Plugins/Android (Android) or Assets/Plugins/iOS (iOS).

  1. If you are upgrading from an earlier version of the MoPub Unity plugin, follow the instructions here to delete old directories.

  2. From the Unity menu bar, select MoPubManage SDKs.

    SDK Manager

  3. Click Install for any mediation network you want to integrate. Doing so downloads the desired network’s .unitypackage archive containing the adapters, as well as the dependencies XML required for the External Dependency Manager.

  4. For Android, we strongly recommend compiling your app against the ads dependencies from Google Play services in order to use the Android Advertising ID instead of the device ID, as required by Google. Those dependencies are and

Option 2. Integrate Manually

  1. Download the latest MoPub Unity plugin here.

  2. To import the MoPub Unity plugin, double-click on the MoPubUnityPlugin.unitypackage, or go to AssetsImport PackageCustom Package. Keep all the files in the Importing Package window selected, and click Import.

  3. If you do not use mediation, skip this step.
    • Download the mediation adapters for the corresponding platform you are building for. On Android, adapters are released as AAR files. On iOS, adapters are released as .h and .m files. Once downloaded, drag and drop the adapter files to the corresponding directories listed in step 4 below.
    • Download the ad network SDK binaries by navigating to the dedicated ad network page. Ensure you are importing that network’s platform SDKs (Android and iOS), and not its Unity SDK/plugin. Make sure you are using the certified version by referencing the Mediation Integration Tool.
  4. Place any required binaries in your Unity project according to the file extensions, as shown:

    SDK File Type Path to place the network SDKs Note
    (.aar and .jar)
    [UNITY PROJECT ROOT]/Assets/Plugins/Android If required by any libraries, add Google Play services aars to this directory.
    (.framework, .h, and .m files)
    [UNITY PROJECT ROOT]/Assets/Plugins/iOS Manually add any required frameworks to your project in Xcode if needed.
    (Note: iOS publishers using MoPub plugin version 5.x with a Unity version below 2017.1 must update to MoPub plugin version 5.0.1 or higher, and review the preceding steps.)
  5. For Android, resolve any pending dependencies by using the Assets > Play Services Resolver > Android Resolver > Force Resolve option.

  6. Build and run your Unity project.

Additional Requirements for Unity 2020+

To prevent issues with your MoPub integration on Android, ensure your Unity 2020 application has the following gradle properties:


If you have further issues, ensure multidex has been enabled as well.

For more details on the above, refer to the following documentation:

NOTE: The underlying cause of the issue is a Gradle upgrade Unity 2020 includes, so if you manually update Gradle to 3.5.0 or above you will still need the above requirements even if not on Unity 2020.

Step 2. Initialize the SDK

Follow these instructions to initialize the SDK.

Step 3. Configure Ad Units in Your App

  1. Depending on the ad format you are integrating, load the plugin for it as shown below:

  2. Then, follow the next steps to finish integrating that ad format:

Rate Limiting

MoPub SDK imposes minimum wait times in between subsequent requests when an ad request is not filled. To avoid this from happening please follow these steps.

Unity Build Systems

To avoid Android build issues caused by the dex list being too large, switch to Gradle in Build SettingsAndroidBuild System.

If you are integrating with v5.6.0 or later of the MoPub SDK, specify the sourceCompatibility and targetCompatibility as below to prevent potential compilation errors:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8

External Dependency Manager

Both integration options (the SDK Manager and the manual integration) download the desired network’s .unitypackage archive containing the adapters, as well as the dependencies XML required for the External Dependency Manager, used for dependency resolution. Once the package’s content is imported, depending on the build platform you have specified in Unity, the External Dependency Manager will handle resolving the dependencies differently:

  • For Android, the External Dependency Manager downloads adapter and SDK JARs/AARs to Assets/Plugins/Android.

    Note that there is a known issue with the External Dependency Manager when resolving Android dependencies. It occasionally leaves the progress bar up indefinitely (or until you exit Unity) even though the resolution process has completed. Unity itself is not blocked, but a side effect is that Unity dialog boxes (like the SDK Manager window) can’t be closed with the usual red close button in the top left of the window; you must use the OK or Done button in the dialog.

  • For iOS, the External Dependency Manager works during the build process. Xcode runs specified pod commands to fetch adapter and SDK pods (the External Dependency Manager attempts to install CocoaPods itself if it doesn’t detect it.)

  • In AssetsPlay Services Resolver, you can find a settings dialog for the External Dependency Manager, where you can customize its behavior, including whether to perform resolution automatically (for Android), and whether to enable verbose logging. The latter option is recommended if you experience any difficulties using the Resolver.

  • You may notice that libraries are downloaded when you try to delete them from disk. This is an intended behavior of the External Dependency Manager. To permanently delete a downloaded adapter or network SDK, delete the network’s Dependencies.xml file (e.g. AdMobDependencies.xml).

Last updated August 28, 2021

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.

© 2021 MoPub (a division of Twitter, Inc.)