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. Initialization is required for a number of new functionalities:

For older MoPub SDK versions (v5.0.0 to v5.4.1), initializing is required for:

  • GDPR consent mechanisms
  • Rewarded video pre-initialization
  • Starting with MoPub SDK v5.2.0, you cannot request ads prior to SDK initialization completion.

For MoPub SDK v5.5.0 and higher, initializing is required for:

  • GDPR consent mechanisms
  • Initialization of mediation SDKs
  • Logging
  • Advanced Bidding
  • Legitimate Interest

Note:: 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.

Instructions

Call the MoPub.initializeSdk() with any valid ad unit once per app’s lifecycle, typically on app launch. Make no ad requests until the SDK initialization has completed.

  1. In your Activity’s onCreate() (or equivalent method), instantiate an SdkConfiguration via a Builder with:

    • any valid ad unit ID from your app
    • your mediation settings (optional)
    • log level (optional)
    • map of configurations for networks (optional)
    • a list of adapter configuration class names to initialize (optional)

    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 automatically attempts to initialize all known networks. However, publishers can specify additional networks via the SDK configuration object as shown in the example below.

The .withMediationSettings API enables you to pass in third-party network specific settings. 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, the MoPub SDK does not cache any network parameters entered in the UI, so network initialization occurs without publisher-specific data. Depending on the mediation network SDK, initializing with no data may result in no action on the part of that network SDK. After the initial ad request succeeds, data is cached and available for use in network initialization attempts when MoPub initializes on subsequent app launches. Refer to Traditional Mediation: With Data - Initial App Launch for a power use case. Some networks do not initialize because of different code requirements (for example, different types of Context). When this happens, that network skips initializing when MoPub initializes on app launches, but 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, data is always available to initialize networks, even on the very first app launches. Note that with this approach, the publisher-supplied data remains active and is used for subsequent ad requests, and parameters entered on the MoPub UI are ignored. Some networks do not initialize because of different code requirements (for example, different types of Context). When this happens, that network skips initializing when MoPub initializes on app launches, but will be initialized at the time of the ad request. On Android, networks known to not initialize due to Context restrictions are 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 our instructions to initialize your network SDKs for Advanced Bidding for a workaround. See Traditional Mediation: All App Launches for context. Refer to our instructions to initialize your network SDKs for Advanced Bidding 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 this 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 our instructions to initialize your network SDKs for Advanced Bidding for a workaround to initialize network SDKs before MoPub. See Traditional Mediation: All App Launches for context. Refer to our instructions to initialize your network SDKs for Advanced Bidding to initialize network SDKs before MoPub.

Logging Information

The MoPub SDK v5.5.0 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 v5.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, refer to the Legitimate Interest section of our GDPR Guide. 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 among the Supported Mediation Partners:

  • Use the subclass BaseAdapterConfiguration. For instructions on how to extend that abstract class, refer to “Build SDK Mediation Adapters for Android”.

  • 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. Refer to the example below.

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.getName())
                                                    .withMediatedNetworkConfiguration(CustomAdapterConfiguration1.class.getName(), mediatedNetworkConfiguration)
                                                    .withMediatedNetworkConfiguration(CustomAdapterConfiguration2.class.getName(), mediatedNetworkConfiguration)
                                                    .withMediatedNetworkConfiguration(CustomAdapterConfiguration1.class.getName(), mediatedNetworkConfiguration1)
                                                    .withMediatedNetworkConfiguration(CustomAdapterConfiguration2.class.getName(), 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 March 23, 2020

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.

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