Initialize the MoPub SDK for Android

After you have integrated the MoPub SDK and created an ad unit, you must call MoPub.initializeSdk() before you send any ad requests. Note: Starting with the 5.2.0 SDK release, requesting ads without and prior to SDK initialization completion is a no-op.

You will need to call the MoPub.initializeSdk() with any valid ad unit once per app’s lifecycle, typically on app launch. Initialization is required for several functions, including:

v5.0.0 to v5.4.1:

  • GDPR consent mechanisms
  • Rewarded video pre-initialization

v5.5.0 and above:

  • GDPR consent mechanisms
  • Mediation SDKs initialization
  • Logging
  • Advanced Bidding
  • Legitimate Interest

If you have been using MoPubRewardedVideos.initializeRewardedVideo(), its function is now included in the new initialization, so make sure to remove all the MoPubRewardedVideos.initializeRewardedVideo() calls from your code.

Initialization Instructions

To initialize the MoPub SDK:

  1. In your Activity’s onCreate() (or equivalent), instantiate an SdkConfiguration via a Builder with any valid ad unit ID from your app, (optional) your mediation settings, (optional) log level, (optional) map of configurations for networks, and (optional) a list of adapter configuration class names to initialize. Note that using an empty ad unit ID for initialization results in an SDK crash with an IllegalArgumentException.
  2. Call MoPub.initializeSdk() and pass in a Context (we recommend the Activity type), the SdkConfiguration object, and an SdkInitializationListener object.

Network SDK initialization

SDK initialization will automatically attempt to initialize all known networks. However, publishers will be given the option to specify additional networks via the SDK configuration object as shown in the example below. .withMediationSettings API enable you to pass in third-party network specific settings. Note that you can call .withMediatedNetworkConfiguration() on your SdkConfiguration.Builder to pass network configurations required for pre-initialization. Otherwise expect your first attempt to pre-initialize mediated networks to fail because no network data is cached at this point. All your subsequent attempts to pre-initialize should succeed for the duration of the app’s life.

Behavior Matrix

Below is a breakdown of the different use cases of network initialization and the corresponding behaviors.

  Initial App Launch All App Launches
Traditional Mediation: No Data At this time, there are no network parameters entered on the UI cached by the MoPub SDK, so network initialization will happen without publisher-specific data. Depending on the mediation network SDK, initializing with no data may mean that no action will occur on its end. Once the initial ad request has succeeded, data will be cached and made available for use in network initialization attempts on subsequent app launches when MoPub initializes. See Traditional Mediation: With Data - Initial App Launch for a power use case. Select networks do not initialize due to different code requirements (e.g. different types of Context). When this is the case, the network SDK in question will skip initializing on app launches when MoPub initializes, and will be initialized at the time of the ad request. On Android, networks known to not initialize due to Context restrictions are Chartboost, Unity Ads, and ironSource.
Traditional Mediation: With Data Publishers can pass in specific parameters for network initialization via withMediatedNetworkConfiguration(). This way, there are always data with which to initialize networks, even on the very first app launches. Note that if this approach is used, the publisher-supplied data will remain active and be used for subsequent ad requests, and parameters entered on the MoPub UI will be ignored. Select networks do not initialize due to different code requirements (e.g. different types of Context). When this is the case, the network SDK in question will skip initializing on app launches when MoPub initializes, and will be initialized at the time of the ad request. On Android, networks known to not initialize due to Context restrictions are Chartboost, Unity Ads, and ironSource.
Advanced Bidding: No Data See Traditional Mediation: No Data - Initial App Launch. Typically, there is no bidding token in this case because the network SDK does not initialize, resulting in the initial ad request not being treated as an Advanced Bidding request. Refer to these instructions for a workaround. See Traditional Mediation: All App Launches for context. Refer to these instructions to initialize network SDKs before MoPub.
Advanced Bidding: With Data See Traditional Mediation: With Data - Initial App Launch. There likely is a bidding token in this case (but that is not guaranteed), because the network SDK could initialize. In case the network SDK does not finish initializing, there may be no bidding token. Refer to these instructions for a workaround to initialize network SDKs before MoPub. See Traditional Mediation: All App Launches for context. Refer to these instructions to initialize network SDKs before MoPub.

Logging Information

The MoPub 5.5.0 SDK enhances the logging experience to include more detailed information such as adapter version, SDK version and ad life cycle events and operations. You can enable these debug logs using the API withLogLevel() during initialization.

Legitimate Interest

The MoPub SDK 5.5.0 now enables mediated networks to collect your user’s personal data based on legitimate interest basis when publishers opt-in. For more details read here. You can enable the legitimate interest flag using the API withLegitimateInterestAllowed() during initialization.

Initialize Custom Ad Networks

Follow these instructions to initialize custom network SDKs not listed on Supported Mediation Partners:

  • Subclass BaseAdapterConfiguration. For instructions on how to extend that abstract class, reference this guide.
  • Pass your adapter configuration custom event class and configurations via the .withMediatedNetworkConfiguration(String, Map<String, String>) to the SdkConfiguration.Builder instance. This adds mediated network configuration keyed by the AdapterConfiguration class.

Example

// configurations required to initialize
Map<String, String> mediatedNetworkConfiguration1 = new HashMap<>();
mediatedNetworkConfiguration1.put("<custom-adapter-class-data-key>", "<custom-adapter-class-data-value>");
Map<String, String> mediatedNetworkConfiguration2 = new HashMap<>();
mediatedNetworkConfiguration2.put("<custom-adapter-class-data-key>", "<custom-adapter-class-data-value>");

SdkConfiguration sdkConfiguration = new SdkConfiguration.Builder("AD_UNIT_ID")
                                                    .withMediationSettings("MEDIATION_SETTINGS")
                                                    .withAdditionalNetworks(CustomAdapterConfiguration.class.toString())
                                                    .withMediatedNetworkConfiguration(CustomAdapterConfiguration1.class.toString(), mediatedNetworkConfiguration)
                                                    .withMediatedNetworkConfiguration(CustomAdapterConfiguration2.class.toString(), mediatedNetworkConfiguration)
                                                    .withMediatedNetworkConfiguration(CustomAdapterConfiguration1.class.toString(), mediatedNetworkConfiguration1)
                                                    .withMediatedNetworkConfiguration(CustomAdapterConfiguration2.class.toString(), mediatedNetworkConfiguration2)
                                                    .withLogLevel(LogLevel.Debug)
                                                    .withLegitimateInterestAllowed(false)
                                                    .build();

MoPub.initializeSdk(this, sdkConfiguration, initSdkListener());

private SdkInitializationListener initSdkListener() {
   return new SdkInitializationListener() {
       @Override
       public void onInitializationFinished() {
           /* MoPub SDK initialized.
           Check if you should show the consent dialog here, and make your ad requests. */
       }
   };
}

Last updated September 11, 2019

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.

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