Integrate the MoPub SDK for iOS

New: Check out the Integration Suite for a faster way to integrate the MoPub SDK.

Use these instructions to integrate the MoPub SDK with your iOS app. If you are upgrading to version 5.0.0 or higher of the SDK, refer to the SDK Initialization and GDPR sections for additional steps.

Requirements

  • iOS 10.0 or higher
  • Xcode 12.0 or higher (MoPub SDK v5.14.0+)

High-Level Steps to Integrate

  1. Download the MoPub iOS SDK.
  2. Integrate the MoPub iOS SDK into your project.
  3. Integrate third-party networks and adapters.
  4. Optionally configure tracking permission alert using ATT framework for iOS 14+.
  5. Configure Audio Session.
  6. Configure ad units in your app.
  7. Prepare for iOS privacy changes.

If you have any questions, don’t hesitate to visit the Support Center and file a ticket.

Step 1. Download the MoPub iOS SDK

You can either download the MoPub SDK source as a zip file, choose to clone the Git repository, or use CocoaPods.

Option 1. Zipped Source

The MoPub SDK is distributed as source code for you to include in your application. MoPub provides two prepackaged archives of source code:

  • MoPub Base SDK.zip includes everything you need to serve Marketplace HTML, MRAID, and native MoPub advertisements. It excludes third-party ad networks.

  • MoPub Base SDK Excluding Native.zip includes everything you need to serve HTML and MRAID advertisements. It excludes third-party ad networks and native MoPub advertisements.

Option 2. Clone the Git Repository

You can either use the bundled zips to install the MoPub SDK, or you can clone the Git repository as follows:

git clone git://github.com/mopub/mopub-ios-sdk.git

The installation instructions are similar to the ones outlined above for the zip archives. To install the base SDK, drag in the contents of the MoPubSDK folder.

Option 3. CocoaPods

The MoPub SDK is available through CocoaPods, a popular dependency management system for Objective-C and Swift projects.

To download and integrate the MoPub SDK into your project using CocoaPods, add the following line to your project’s podfile:

pod 'mopub-ios-sdk'

Option 4. MoPub SDK Frameworks

Starting with MoPub SDK v5.5, we are distributing three versions of the MoPubSDKFramework.framework, which you can download here. The three versions are:

  • Simulator: built with i386 and x86_64 architectures
  • Device: built with armv7 and arm64 architectures
  • Universal: includes simulator and device architectures

We recommend that you use the universal framework during development and testing process, and use the device framework when submitting to the app store.

Step 2. Integrate the MoPub iOS SDK into Your Project

You can either integrate the MoPub SDK into your project using the CocoaPods recommended implementation, the using Swift, or manually.

Option 1. Integrate the SDK Using CocoaPods

  • New CocoaPods setup: If you are setting up CocoaPods for the first time, run pod install.
  • Existing CocoaPods project: If you are adding MoPub to an existing CocoaPods project have CocoaPods, run pod update.

Your project is now ready to use the base MoPub SDK.

MoPub SDK includes Swift code starting v5.15.0+ and hence you will need to enable “Always Embed Swift Standard Libraries”. This will increase the binary size supporting older versions of iOS (< 12.4) if the codebase doesn’t already contain Swift code.

Option 2. Integrate Using Swift

To use the MoPub SDK in your Swift project, simply import MoPubSDK/MoPub-Bridging-Header.h to your project and ensure that the Objective-C Bridging Header build setting under Swift Compiler - Code Generation has a path to the header.

The MoPub iOS SDK repository on GitHub also hosts and maintains a Swift sample app that you can reference.

Option 3. Integrate the SDK Manually

  1. Drag the MoPubSDK folder into your Xcode application group (be sure to select the Copy items into destination group’s folder option).

    image

    image

  2. Add the following frameworks to your project by clicking on your application’s target, then clicking Build Phases and expanding the Link Binary With Libraries group.

    The MoPub Base SDK requires the following frameworks:

    • AdSupport.framework
    • AVFoundation.framework
    • CoreGraphics.framework
    • CoreLocation.framework
    • CoreMedia.framework
    • CoreTelephony.framework
    • Foundation.framework
    • MediaPlayer.framework
    • MessageUI.framework
    • QuartzCore.framework
    • SafariServices.framework
    • StoreKit.framework
    • SystemConfiguration.framework
    • UIKit.framework
    • WebKit.framework
  3. For apps using Manual Reference Counting (MRC), tell the compiler to build the MoPub iOS SDK source files with ARC. This is easy to do and has no impact on your application:

    1. Click on your application’s target, then click Build Settings.
    2. Set the Weak References in Manual Retain Release setting to ‘YES’.
    3. Click Build Phases and expand the Compile Sources group.
    4. Select all the MoPubSDK source files. (They are grouped together near the end if you have recently dragged in the SDK.)
    5. Scroll down and double-click on the last file. A blank popup appears.
    6. Enter -fobjc-arc and press [Enter] to add the -fobjc-arc flag to all the selected files.

Step 3. Integrate Third-Party Ad Networks and Adapters

Refer to this tutorial for the integration details.

Step 4. Optionally Configure Tracking Permission Alert Using ATT Framework for iOS 14+

Tracking Permission Prompt

iOS 14 AppTrackingTransparency (ATT) framework presents an app-tracking authorization request to the user and provides the tracking authorization status. Learn more about ATT here. MoPub now follows the ATT framework, and uses ATT to retrieve the user’s authorization status.

SKAdNetwork Attribution Solution

As an attribution solution in the absence of consistent IDFAs, Apple has provided the SKAdNetwork API.

To configure your app with SKAdNetwork IDs, add the MoPub SKAdnetwork ID and the IDs of all the DSPs to whom you want to sell to your Info.plist file. Doing so indicates that your app wants to work with MoPub and accept bids from these buyers. Follow these instructions from Apple.

The SKAdNetwork IDs for MoPub and MoPub buyers are hosted in two formats. Note that these files are frequently updated; the following locations always have the most current list:

Use MoPub’s SKAdNetwork IDs Manager tool to make quick work of gathering and processing the SKAdNetwork IDs. Our intuitive tool processes and deduplicates SKAdNetwork IDs for MoPub, Marketplace buyers, and MoPub’s supported partners, then generates a finalized Info.plist output for you, so that you can easily integrate it into your app. The tool also lets you add any SKAdNetwork IDs you already have to your final Info.plist.

Step 5. Configure Audio Session

MoPub uses the Apple iOS WKWebView to render HTML (including MRAID) creative. As designed by Apple, WKWebView respects the volume settings only and does not respect the Audio Session Category set by the application.

MoPub uses the OS provided media player (AVPlayer) for Fullscreen and Rewarded VAST Video Ads that respects the Audio Session Category set by the app. However, it is important to handle audio interruptions from these ads gracefully depending on your chosen Audio Session Category, as the ad’s audio may mix in with the app’s audio. Apple provides a Programming Guide for responding to audio interruptions, allowing your app to pause app audio while the interstitial is on screen.

Important: For publishers using the Audio Session Categories of AVAudioSessionCategoryAmbient or AVAudioSessionCategorySoloAmbient (default), note that WKWebView does not respect the silent/ringer switch because it has its own Audio Session.

Step 6. Configure Ad Units in Your App

Once you’ve completed the above steps, you can start displaying ads in your application by configuring the ad units as shown in the link below for your ad format:

Step 7. Prepare for iOS Privacy Changes

To minimize negative revenue impact to your apps, we encourage you to consider these key steps. See our blog for more details.

  1. Begin testing your prompt implementation now so that you have a winning strategy to maximize IDFA collection when the prompt is enforced. Given the limited flexibility of the prompt and the fact that users can only be prompted once, consider adding a custom ‘pre-prompt’ which will allow you to elaborate on the impact of a user opting in/out. A benefit of this is that you can use your own native designs and copy for the pre-prompt. Employing a transparent and clear approach can help contribute to user trust, which may make them more open to providing IDFA consent.

  2. Update your app with relevant partner SDK versions. In the absence of consistent IDFAs, Apple has provided the SKAdNetwork API as an attribution framework. Ensure that you have updated to the latest version of your monetization partner SDKs that support the SKAdNetwork API. MoPub supports the SKAdNetwork API through our 5.14+ SDKs for publishers and through our programmatic exchange for demand partners. The latest MoPub SDK updates also support SKAdNetwork v2.2+, which include support for View-Through Attribution (VTA).

  3. Make sure your app’s Info.plist file is updated with the IDs of all of your monetization partners. To configure your app with SKAdNetwork IDs, add the MoPub SKAdNetwork ID and the IDs of all the DSPs to whom you want to sell to your Info.plist file. Doing so indicates that your app wants to work with MoPub and accept bids from these buyers. See our iOS integration guide for more details.

  4. Use MoPub’s SKAdNetwork IDs Manager tool to gather and process your relevant SKAdNetwork IDs. You can use this tool even if you do not work with MoPub. Our tool processes and deduplicates SKAdNetwork IDs for MoPub, Marketplace buyers, and MoPub supported partners as well as non-supported third party lists and publisher custom lists then generates a finalized Info.plist output so that you can easily integrate it into your app.

  5. Consider leveraging MoPub’s impression-level revenue data (ILRD) to help capture the most useful performance measurement. More information on this as well as some example implementations for it are available here.


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