Initialize the MoPub SDK for iOS

The MoPub 5.0 SDK introduces a new API for initialization called [[MoPub sharedInstance] initializeSdkWithConfiguration:sdkConfig completion:nil]. This API is required for a number of new functionalities, 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

Note: If you have been using [[MoPub sharedInstance] initializeRewardedVideoWithGlobalMediationSettings], it is now part of the new initialization, so make sure to switch to the new API.


You only need to initialize once using any valid ad unit ID from your app. Ad requests should only be made once the SDK initialization has completed.

  1. In your app’s didFinishLaunchingWithOptions:, instantiate a MPMoPubConfiguration with any valid ad unit ID from your app, your mediation settings (optional), (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 NSInternalInconsistencyException.
  2. Call initializeSdkWithConfiguration: and pass in your MPMoPubConfiguration instance.

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. globalMediationSettings API enable you to pass in third-party network specific settings. Note that you can call .mediatedNetworkConfigurations on your MPMoPubConfiguration 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.

The list of supported adapters that the MoPub SDK will use to initialize is located in MPAdapters.plist. This file must exist in the MoPubSDK/Resources/ directory path for initialization to take place. Any change to the path might cause the network adapters not to initialize correctly.

Behavior Matrix

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

  Traditional Mediation Advanced Bidding
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. See Traditional Mediation: No Data. 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.
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. See Traditional Mediation: With Data. 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.

Logging Information

The MoPub 5.5.0 SDK has enhanced logging formats to include more detailed information such as adapter version, SDK version, and ad life cycle events and operations. You can enable these debug logs by setting MPBLogLevel to MPBLogLevelDebug 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 .allowLegitimateInterest during initialization.

Initialize Custom Ad Networks

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

  • Subclass MPBaseAdapterConfiguration. For instructions for how to implement that interface, reference this guide.
  • Set the network configuration options for a given mediated network class name by using the dictionary mediatedNetworkConfigurations. Refer to the example below.


MPMoPubConfiguration *sdkConfig = [[MPMoPubConfiguration alloc] initWithAdUnitIdForAppInitialization:@"AD_UNIT_ID"];

sdkConfig.globalMediationSettings = @[];
sdkConfig.loggingLevel = MPBLogLevelInfo;
sdkConfig.allowLegitimateInterest = BOOL;
sdkConfig.additionalNetworks = @[NetworkAdapterConfiguration.class];
sdkConfig.mediatedNetworkConfigurations = NSMutableDictionary<NSString, NSDictionary<NSString, id>> of data to be passed to mediation adapters for initialization;

[[MoPub sharedInstance] initializeSdkWithConfiguration:sdkConfig completion:^{
        NSLog(@"SDK initialization complete");
        // SDK initialization complete. Ready to make ad requests.

Last updated January 02, 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.)