Initialize the MoPub SDK for iOS

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

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 [[MoPub sharedInstance] initializeRewardedVideoWithGlobalMediationSettings], it is now part of the new initialization, so make sure to switch to the new API.

Instructions

Initialize once per app’s lifecycle, typically on app launch, using any valid ad unit ID that belongs to the specific app you’re initializing with MoPub. Using a valid ad unit ID from the correct app improves the accuracy of the DAU metric tracking for your app. Make no ad requests until 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)
    • 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 NSInternalInconsistencyException.

  2. Call initializeSdkWithConfiguration: and pass in your MPMoPubConfiguration instance.

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 globalMediationSettings API enables you to pass in third-party network specific settings. 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, 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. 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 our instructions to initialize your network SDKs for Advanced Bidding for a workaround.
With Data Publishers can pass in specific parameters for network initialization via MPMoPubConfiguration.mediatedNetworkConfigurations. 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. See Traditional Mediation: With Data. 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.

Logging Information

The MoPub SDK v5.5.0 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 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 .allowLegitimateInterest during initialization.

Initialize Custom Ad Networks

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

  • Use the subclass MPBaseAdapterConfiguration. For instructions for how to implement that interface, refer to “Build SDK Mediation Adapters for iOS”.

  • Set the network configuration options for a given mediated network class name by using the dictionary mediatedNetworkConfigurations. Refer to the example below:

Example

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 September 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.)