Integrating MoPub with Mediation

This guide is intended for publishers who want to use the Google Mobile Ads SDK to load and display ads from MoPub via mediation. It covers how to add MoPub to an ad unit's mediation configuration, and how to integrate the MoPub SDK and adapter into a Unity app.

Supported ad formats and features

The AdMob mediation adapter for MoPub has the following capabilities:

Formats
Banner
Interstitial
Rewarded
Features
Adaptive banner
Ad network optimization (ANO)

Requirements

  • Unity 4 or higher
  • Latest Google Mobile Ads SDK
  • To deploy on Android
    • Android API level 16 or higher
  • To deploy on iOS
    • iOS deployment target of 8.0 or higher
  • A working Unity project configured with Google Mobile Ads SDK. See Get Started for details.

Step 1: Set up MoPub

First, sign up (if you haven't already) and log in to your MoPub UI. Navigate to the Apps page and click the Add a New App button.

MoPub new app

Select the Platform for which you would want to set up Unity Ads. If your app supports both platforms (Android and iOS), you need to add your apps separately for each platform.

Enter the Name of your app, Package name of your app, and select a primary and secondary category of your app from the provided list.

MoPub app

MoPub requires you to create your first Ad Unit before completing the registration of your app.

For additional instructions on creating an ad unit, select the tab corresponding to your preferred ad format.

Choose Tablet as the Device type. Choose a banner format that matches the ad size you're requesting in your app. Enter a Name for your Ad Unit.

The refresh rate is handled by the Google Mobile Ads SDK according to your refresh rate setting in the UI. So, we recommend using a high value for the Refresh Interval here (e.g. 1000 seconds).

Interstitial

Choose Tablet as the Device type. Choose Fullscreen Tablet as the Format. Enter a Name for your Ad Unit. Choose the type of Layout to present the ad in.

Click Save and View Code Integration to get your Ad Unit ID.

MoPub ad unit id

We will use this Ad Unit ID to set up your AdMob Ad Unit ID for mediation in the next section.

MoPub Marketplace

To get ads from MoPub, your account needs to be approved for MoPub Marketplace. During your initial account setup, you will be prompted to go through the process for Marketplace approval. Part of this process includes entering your payment information.

MoPub marketplace

See Marketplace setup for more details.

Step 2: Configure AdMob Ad Unit

You need to add MoPub to the mediation configuration for your Ad Unit. First sign into the AdMob UI.

If you're deploying your Unity app to both Android and iOS, you need two AdMob ad units, one for each platform.

Navigate to the Mediation tab. If you have an existing mediation group you'd like to modify, click the name of that mediation group to edit it, and skip ahead to Add MoPub as an ad source.

To create a new mediation group, select Create Mediation Group.

AdMob mediation tab

Enter your ad format and platform, then click Continue.

Android

Give your mediation group a name, and select locations to target. Next, set the mediation group status to Enabled. Then click Add Ad Units, which will open up the ad unit selection overlay.

New mediation group 2

Associate this mediation group with your existing AdMob ad unit. Then click Done.

Select ad unit

You should now see the ad units card populated with the ad units you selected.

Mediation group ad units

iOS

Give your mediation group a name, and select locations to target. Next, set the mediation group status to Enabled. Then click Add Ad Units, which will open up the ad unit selection overlay.

New mediation group 2

Associate this mediation group with your existing AdMob ad unit. Then click Done.

Select ad unit

You should now see the ad units card populated with the ad units you selected.

Mediation group ad units

Add MoPub as an ad source

In the Ad Sources card, select Add Ad Network. Then select MoPub.

Enable the Optimize switch. Enter the API Key and Inventory Report ID obtained in the previous section to set up ANO for MoPub. Then enter an eCPM value for MoPub and click Continue.

Enter the Ad Unit ID obtained in the previous section and click Done.

Android

Configure MoPub ad unit

iOS

Configure MoPub ad unit

Finally, click Save.

Using rewarded ads

In the settings for your rewarded ad unit, check the Apply to all networks in Mediation groups box so that you provide the same reward to the user no matter which ad network is served.

Mediation override reward

If you don't apply this setting, the MoPub adapter passes back the reward specified in the MoPub dashboard.

For more information on setting reward values for AdMob ad units, see Create an ad unit.

Step 3: Import the MoPub SDK and adapter

Download the latest version of Google Mobile Ads mediation plugin for MoPub from the download link in the Changelog and extract the GoogleMobileAdsMoPubMediation.unitypackage from the zip file.

In your Unity project editor, select Assets > Import Package > Custom Package and find the GoogleMobileAdsMoPubMediation.unitypackage file you downloaded. Make sure that all the files are selected and click Import.

Then, select Assets > Play Services Resolver > Android Resolver > Force Resolve. The Unity Play Services Resolver library will perfrom dependency resolution from scratch and copy the declared dependencies into the Assets/Plugins/Android directory of your Unity app.

Step 4: Additional code required

Initialize the MoPub SDK

Before loading ads, have your apps initialize the MoPub SDK. The Google Mobile Ads mediation plugin for MoPub version 2.3.1 includes the MoPub.Initialize() method to initialize the MoPub SDK with any valid MoPub ad unit ID that you created in Step 1. This needs to be done only once, ideally at app launch.

...
using GoogleMobileAds.Api;
using GoogleMobileAds.Api.Mediation.MoPub;

public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    public void Start()
    {
        // Initialize the Google Mobile Ads SDK.
        MobileAds.Initialize(initStatus => { });

        // Initialize the MoPub SDK.
        MoPub.Initialize("YOUR_MOPUB_AD_UNIT_ID");

        ...
    }
}

Android

No additional code required.

iOS

No additional code required.

Step 5: Test your implementation

To get test ads from MoPub, you need a guaranteed or backfill line item. MoPub recommends adding the Demo line item to your Ad Unit to get test ads. The Demo line item is added to your MoPub account by default.

MoPub demo item

The Demo Line Item contains test creatives for native and banner ad units by default, but does not have a test creative for interstitial ad units. To add your own test creative for interstitial ads, you need to upload a simple image to the MoPub UI by navigating to the Demo Line Item and clicking the Add a New Creative button. Choose Tablet Full Screen format. Fill the form with the necessary details and click Save to add your test creative to the Demo Line Item.

MoPub creative

That's it! You now have a working mediation integration with MoPub.

Optional steps

Under the Google EU User Consent Policy, you must ensure that certain disclosures are given to, and consents obtained from, users in the European Economic Area (EEA) regarding the use of device identifiers and personal data. This policy reflects the requirements of the EU ePrivacy Directive and the General Data Protection Regulation (GDPR). When seeking consent, you must identify each ad network in your mediation chain that may collect, receive, or use personal data and provide information about each network's use. Google currently is unable to pass the user's consent choice to such networks automatically.

MoPub's Unity plugin offers APIs to help you collect consent for MoPub. The following steps explain how to import the MoPub Unity plugin in a way that doesn't conflict with the Google Mobile Ads mediation plugin for MoPub that you installed earlier.

Download the MoPub Unity plugin that depends on the same MoPub iOS SDK version as the Google Mobile Ads Mediation plugin:

  1. Refer to the mediation plugin for MoPub changelog and look at the release notes for the version you installed.

  2. Find which MoPub iOS adapter version is included with that Unity plugin version. For example, version 2.8.0 of the Unity mediation plugin depends on version 5.6.0.1 of the iOS MoPub adapter, which uses MoPub iOS SDK 5.6.0 per the iOS adapter versioning scheme.

  3. Download the MoPub Unity plugin that depends on the MoPub iOS SDK determined from the previous step. Following the above example, MoPub Unity plugin 5.6.0 is the version that uses MoPub iOS SDK 5.6.0.

After downloading the correct Mopub Unity plugin, select Assets > Import Package > Custom Package in your Unity project editor and find the MoPubUnity.unitypackage file you downloaded. Make sure to uncheck the following files from the MoPub/Plugins/Android folder:

  • mopub-sdk-banner.aar
  • mopub-sdk-base.aar
  • mopub-sdk-interstitial.aar
  • mopub-sdk-native-static.aar
  • mopub-sdk-rewardedvideo.aar
  • mopub-volley-x.x.x.jar

MoPub plugin import

Now that you installed the MoPub Unity plugin, you are ready to implement their consent solution. Please consult MoPub's guides for more information:

Android permissions

If the user's location needs to be used for the targeting, MoPub recommends adding the following optional permission into your app's AndroidManifest.xml file:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

MoPub recommends adding the following optional permission for MRAID 2.0:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Error codes

If the adapter fails to receive an ad from MoPub, publishers can check the underlying error from the ad response using ResponseInfo under the following classes:

Android

com.google.ads.mediation.mopub.MoPubAdapter
com.google.ads.mediation.mopub.MoPubMediationAdapter

iOS

GADMAdapterMoPub
GADMediationAdapterMoPub

Here are the codes and accompanying messages thrown by the MoPub adapter when an ad fails to load:

Android

Error code Reason
101 MoPub server parameters configured in the AdMob UI are missing/invalid.
102 The requested banner size does not map to a valid MoPub ad size.
103 Activity context is null.
104 Mopub SDK not initialized.
105 Wrong native ad type.
107 An ad is already loaded for this network configuration.
108 Ad expired.
110 Requires native ads.
111 Native ad is missing required assets.
112 Ad is not ready.
0-99 MoPub SDK error. See code for more details.
1000-1099 MoPub native ads error. See code for more details.

iOS

Error code Reason
100 The MoPub SDK sent an ad load failure callback.
101 An ad is already loaded for this network configuration.
102 There was an error loading data from the network.
103 MoPub server parameters configured in the AdMob UI are missing/invalid.
104 The requested ad size does not match a MoPub supported banner size.
105 Banner ad size is smaller than minimum banner size set by the publisher.
-1, 0, 1-38 MoPub SDK error. See code for more details.

MoPub Unity Mediation Plugin Changelog

Version 2.16.0

Version 2.15.0

Version 2.14.0

Version 2.13.0

Version 2.12.1

Version 2.12.0

Version 2.11.0

Version 2.10.0

Version 2.9.0

Version 2.8.0

  • Supports MoPub Android adapter version 5.7.1.0.
  • Supports MoPub iOS adapter version 5.6.0.1.

Version 2.7.0

  • Updated the plugin to support the new Rewarded API.
  • Supports MoPub Android adapter version 5.4.1.2.
  • Supports MoPub iOS adapter version 5.6.0.1.

Version 2.6.0

  • Supports MoPub Android adapter version 5.4.1.1.
  • Supports MoPub iOS adapter version 5.5.0.0.

Version 2.5.1

  • Added support for loading Rewarded Video Ads from MoPub.
  • Supports MoPub Android adapter version 5.4.1.1.
  • Supports MoPub iOS adapter version 5.4.1.1.

Version 2.5.0

  • Supports MoPub Android adapter version 5.4.1.0.
  • Supports MoPub iOS adapter version 5.4.1.0.

Version 2.4.0

  • Supports MoPub Android adapter version 5.3.0.1.
  • Supports MoPub iOS adapter version 5.4.0.0.

Version 2.3.1

  • Fixed an issue where the MoPub API files were not included when importing the plugin.
  • Supports MoPub Android adapter version 5.3.0.1.
  • Supports MoPub iOS adapter version 5.3.0.1.

Version 2.3.0

  • Supports MoPub Android adapter version 5.3.0.0.
  • Supports MoPub iOS adapter version 5.3.0.0.

Version 2.2.0

  • Supports MoPub Android adapter version 5.2.0.0.
  • Supports MoPub iOS adapter version 5.2.0.0.
  • Added the following methods:
    • MoPub.Initialize() method to initialize the MoPub SDK prior to sending an Ad Request.
    • MoPub.IsInitialized() method to check if the MoPub SDK has been initialized.

Version 2.1.0

  • Supports MoPub Android adapter version 5.1.0.0.
  • Supports MoPub iOS adapter version 5.1.0.0.

Version 2.0.0

  • Supports MoPub Android SDK version 5.0.0.
  • Supports MoPub iOS SDK version 5.0.0.

Version 1.0.0

  • First release!
  • Supports MoPub Android SDK version 4.20.0.
  • Supports MoPub iOS SDK version 4.20.1.