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 ad 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

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.

Initialize Your Network SDKs for Advanced Bidding

Ensure that all networks using Advanced Bidding are initialized as early as possible. This means doing so “outside of the MoPub integration”; that is, before MoPub is initialized, for sufficient lead time to generate a successful bid.

The following is a generalized approach to initializing networks outside of MoPub:

  1. On app launch, identify where the app initializes MoPub, and preface it a couple of lines. This is where you will initialize the network SDKs.

  2. Call the corresponding initialization API from the network SDK to initialize it, and pass in any parameters or IDs as necessary.

  3. Once the network finishes initializing, after a predefined wait time, initialize MoPub.

  4. Once MoPub finishes initializing via the completion callback, make the ad request.

Below we use AdColony as our example, but all Advanced Bidding networks must be initialized this way. If you have questions about a specific network, please contact your account team.

Example:

    // Define the AdColony app and zone IDs you want to initialize with
    NSString * appId = @"your_app_id";
    NSArray * allZoneIds = [NSArray arrayWithObjects:@"rewardedZoneId",@"interstitialZoneId"];
    NSString * userId = @"your_user_id";

    // Initialize the AdColony SDK with the above IDs
    [AdColonyController initializeAdColonyCustomEventWithAppId:appId allZoneIds:allZoneIds userId:userId callback:^{
         // Initialize the MoPub SDK
         [[MoPub sharedInstance] initializeSdkWithConfiguration:sdkConfig completion:^{
         }];
    }];

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 August 28, 2021

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.

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