Get started with iOS OpenWrap SDK for MoPub

OpenWrap SDK lets publishers leverage the power of OpenWrap to request multiple programmatic bids for their mobile in-app inventory. OpenWrap sends an initial ad call that goes out to one or more OpenWrap partners requesting bids for inclusion in the ad server’s inventory allocation process.

High-level process overview

  1. OpenWrap SDK calls OpenWrap before requesting an ad from the primary AdServer SDK.
  2. Programmatic buyers get first look at the inventory, submit a bid price, then OpenWrap conducts a server-side auction between bids from different OpenWrap partners configured by the publisher.
  3. OpenWrap includes the winning bid data (including bid eCPM and dealid), in the ad server call, which checks whether other buyers in the same priority tier can beat it. The impression is allocated to the highest yielding buyer while respecting other publisher controls that may have been set up on the ad server
  4. If OpenWrap wins the bid, the ad server returns the winning ad to OpenWrap SDK.
  5. OpenWrap renders any ad returned by the ad server.

You can also let winning bids compete with prices available from direct-sold ads by setting the OpenWrap SDK line items to same priority as your direct sold line items.

OpenWrap SDK provides the following benefits:

  • All the demand sources bid at the same time, replacing the sequential preferential ordering of buyers.
  • Advertisers have the chance to obtain the best ad inventory.
  • Publishers can potentially see up to a 50% monetization increase.

Required dependencies

Development environment 

Xcode 12.5 or greater.

Target environment 

iOS version 10 or greater (iOS 9 support is deprecated in v1.6.2 and will be removed in a future release).

Publisher/Placement Details 

Before integrating OpenWrap SDK in your app to show banner/interstitial/rewarded ad, you must have the following details:

    • Publisher ID

    • OpenWrap Profile ID

    • OpenWrap Ad Unit Id

    • MoPub Ad Unit Id

You can use Pubmatic test profiles only during integration.

OR

You can create the OpenWrap Profile using your own account. Learn more about Profile creation and management inOpenWrap Mobile In-App Support.

Questions?

Contact your PubMatic Account Manager. 
Ad Server Configuration for OpenWrap and SDKThis step is required so the MoPub ad server, based on actual bid price, can allocate impressions to the winning partner. See MoPub ad server setup.
Ad Server SDKYou must Integrate MoPub SDK, to work with the OpenWrap SDK.

Integrate MoPub SDK

Before you start integrating the PubMatic OpenWrap SDK, you must integrate the MoPub SDK in your app. OpenWrap SDK has been tested and certified with  MoPub SDK version 5.13.0 - 5.18.0; see the OpenWrap and MoPub compatibility matrix . OpenWrap SDK should work with newer versions of MoPub, but has not yet been certified with any newer version.

Create a Podfile in your app's Xcode Project directory (the directory containing your .xcodeproj file), if a Podfile doesn't already exist.

If Cocoapods isn't installed see

How to Install CocoaPods. Also see Using CocoaPods to learn to create and use Podfiles.

Now add the following line to the Podfile:

Add MoPub SDK Dependency
pod 'mopub-ios-sdk', '5.18.0'

Once you have integrated the MoPub SDK and created an ad unit, you must initialize the MoPub SDK before you make any ad requests .

Initialize MoPub SDK only once, sending any valid ad unit ID from your app; for example, from your app’s didFinishLaunchingWithOptions: event, similar to the example below. For more information see, MoPub Initialization.

Objective-C Swift

Integrate OpenWrap SDK

Note

You must migrate your app to a later version if it is using either:

  • OpenWrap SDK earlier than 2.0.0.
  • OpenWrap SDK handler earlier than 2.4.0.

See, OpenWrap SDK migration guides.

The next step is to integrate the PubMatic OpenWrap SDK and MoPub event handlers in your app. This is important because it makes the ad server call using MoPub SDK APIs.

You can integrate in one of two ways: use CocoaPods or integrate manually. You'll find the instructions for both below.

Using CocoaPods

Before you begin, check this compatibility matrix to make sure you select an appropriate MoPub handler that satisfies your project's requirements:

OpenWrap and MoPub compatibility matrix

The OpenWrap handler for MoPub is the bridge between OpenWrap SDK and an Ad Server SDK. Use the appropriate OpenWrap handler for your target MoPub version from the table below.

How to read the matrix:

  • If you're using OW SDK v2.3.1 and want to use MoPub SDK v5.16.2 - v5.18.0, you should use handler version 2.4.0.
  • If you're using OW SDK v1.9.0 and want to use MoPub SDK v5.15.0, you should use handler version 1.4.0.
COMPATIBLE OW SDK VERSION(S)USE OW HANDLER VERSIONCOMPATIBLE MOPUB SDK VERSION(S)
2.2.0 - 2.3.12.4.05.16.2 - 5.18.0
2.1.02.3.05.16.0 - 5.16.2
2.0.02.2.05.16.0 - 5.16.2
2.0.02.1.05.13.0-5.15.0
1.9.01.4.05.13.0-5.15.0
1.8.21.3.3-2.0.05.13.0-5.15.0

Follow these steps to integrate using CocoaPods:

MoPub handler version 2.4.0 requires Xcode v12.5.

Step 1: Add the following lines in your Podfile.

Add PubMatic OpenWrap SDK Dependency
pod 'OpenWrapSDK'
pod 'OpenWrapHandlerMoPub'

Your Podfile should now look similar to this:

Example Podfile
platform :ios, '10.0'

target 'SampleApp' do
    pod 'mopub-ios-sdk', '5.18.0'
    pod 'OpenWrapSDK'
    pod 'OpenWrapHandlerMoPub'
end

Step 2: Save the Podfile, then do the following:

  1. Open the Terminal application.
  2. Change to your app's project directory; for example,

    cd /Developer/Projects/MyApp/
  3. Now execute the following command:

    pod install --repo-update

Integrate manually

The the links in steps 1 and 2 download the latest version of the OpenWrap SDK and handler. Check this compatibility matrix to make sure you select an appropriate handler that satisfies your project requirement:

MoPub handler compatibility matrix

Other handler downloads for manual integration

If the latest handler doesn't support the MoPub SDK version that you are using, download the appropriate handler below based on the compatibility matrix.

OpenWrap and MoPub compatibility matrix

The OpenWrap handler for MoPub is the bridge between OpenWrap SDK and an Ad Server SDK. Use the appropriate OpenWrap handler for your target MoPub version from the table below.

How to read the matrix:

  • If you're using OW SDK v2.3.1 and want to use MoPub SDK v5.16.2 - v5.18.0, you should use handler version 2.4.0.
  • If you're using OW SDK v1.9.0 and want to use MoPub SDK v5.15.0, you should use handler version 1.4.0.
COMPATIBLE OW SDK VERSION(S)USE OW HANDLER VERSIONCOMPATIBLE MOPUB SDK VERSION(S)
2.2.0 - 2.3.12.4.05.16.2 - 5.18.0
2.1.02.3.05.16.0 - 5.16.2
2.0.02.2.05.16.0 - 5.16.2
2.0.02.1.05.13.0-5.15.0
1.9.01.4.05.13.0-5.15.0
1.8.21.3.3-2.0.05.13.0-5.15.0


If you are integrating MoPub SDK by manually downloading the frameworks or prepackaged archives, you may need to change the MoPub header imports in the handler files.
For example, change #import<MPAdView.h> to #import<MoPub/MPAdView.h>

Follow these steps to perform a manual integration:

Step 1. Download the OpenWrap SDK zip file.

  • Download and unzip the OpenWrap SDK v2.3.1.
  • Include the OpenWrapSDK folder in your Xcode project and select Copy items if needed while including.

Step 2. Next download Handlers.zip. 

  • Download and unzip the OpenWrap Handlers v2.4.0.
  • Include the OpenWrapHandlerMoPub folder in your Xcode project and select Copy items if needed while including.

Step 3. Now add the following required OpenWrap SDK frameworks to your project:

  • Foundation.framework
  • UIKit.framework
  • MessageUI.framework
  • CoreLocation.framework
  • EventKitUI.framework
  • EventKit.framework
  • AdSupport.framework
  • SystemConfiguration.framework
  • CoreGraphics.framework
  • CoreTelephony.framework
  • WebKit.framework

Step 4. Finally, add the -ObjC linker flag to your project's Build Settings > Targets > Linking > Other Linker Flags:


App Transport Secutiry (ATS)

OpenWrap SDK defaults to secure ad calls and delivers only secure ads using App Transport Security (ATS), an iOS feature that encrypts data in transit using HTTPS, instead of HTTP. ATS enforces a minimum security level for communications between mobile apps and web services that support them. Software development kits (SDKs) for iOS 9.0 or greater enable ATS by default, but developers can opt-out by setting the app’s NSAllowsArbitraryLoads key to True.


If you configure OpenWrap SDK to serve non-secure ads…

If you configure OpenWrap SDK to serve non-secure ads as described in Advanced topics > Configure SSL, then opt-out of ATS as shown in the example below.

The following log message appears when you request a non-ATS compliant ad via HTTP in your app running iOS 9 or greater:

App Transport Security has blocked a cleartext HTTP (http://) resource load since it is insecure. Temporary exceptions can be configured via your app's Info.plist file.

To allow non-secure ads over http, disable ATS by including the following entry in your app's Info.plist file:

App Transport Security Settings
<key>NSAppTransportSecurity</key> 
<dict> 
	<key>NSAllowsArbitraryLoads</key> 
	<true/> 
</dict>

iOS 14 integration

iOS 14 brings several changes to enhance the ad experience for mobile users. See the following section to configure SKAdNetwork in your app.

Request App Tracking Transparency (ATT) authorization

To display the App Tracking Transparency authorization request to access the IDFA, update your  Info.plist  to add the  NSUserTrackingUsageDescription  key with a custom message describing your intended IDFA usage. For example:

Privacy - Tracking Usage Description
<key>NSUserTrackingUsageDescription</key>
<string>The Advertising Identifier helps deliver ads that are relevant to your interests.</string>

The usage description appears in the App Tracking Transparency dialog box:

To present the authorization request, call  requestTrackingAuthorizationWithCompletionHandler: . The best practice is to wait for the completion callback prior to loading ads so that if the user grants the ATT permission, the ad server SDK can immediately use the IDFA in ad requests.

Objective-C Swift

For more information about the possible status values see,  ATTrackingManager.AuthorizationStatus .

Best practices

  • Add a priming message preceding the call to requestTrackingAuthorizationWithCompletionHandler: to better explain the permission and data usage to users.
  • Request the ad only after post-authorization callback. This lets OpenWrap SDK immediately access and pass the IDFA in the ad request if that user approved the IDFA access request. 

Configure SKAdNetwork settings to track conversions

OpenWrap SDK is compatible with iOS 14 and the support for Apple's SKAdNetwork 2.0, which allows mobile apps to install attribution for demand partners buying in-app inventory from iOS 14, while also preserving user privacy. 

To enable install attribution, you must update the SKAdNetworkItems key with additional network ID dictionary entries in your app's  Info.plist .

Get the latest SKAdNetwork ad network IDs

Use the links below for the up-to-date SKAdNetwork list:

Include ad network IDs in your information property list:

  1. Select Info.plist in the Xcode Project navigator.

  2. Click the Add button (+) beside a key in the property list editor, then press Return.

  3. Type the key name,  SKAdNetworkItems.

  4. Choose Array from the pop-up menu in the Type column, then enter the dictionary entries as shown below.

    <array>
     <dict>
       <key>SKAdNetworkIdentifier</key>
       <string>example100.skadnetwork</string>
     </dict>
     <dict>
       <key>SKAdNetworkIdentifier</key>
       <string>example200.skadnetwork</string>
     </dict>
    </array>

If users tap an ad that attempts an API call for an ad network that doesn’t have an entry in the Info.plist, the system won't initiate install validation. Also, note that missing this step can negatively affect the fill rate.


Learn more:

Sample apps

For more integration details, have a look at the OpenWrap SDK sample apps.

Setup MoPub ad server

Before you begin setting up banner and interstitial ads in your app integration, first setup MoPub ad server to work with OpenWrap SDK.

Table of Contents

⇧ Top

Do you have feedback on this document? Let us know: email us.