Get started with iOS OpenWrap SDK for GAM

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 or interstitial ads, you must have the following details:

    • Publisher ID

    • OpenWrap Profile ID

    • OpenWrap Ad Unit ID

    • GAM 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 in, OpenWrap Mobile In-App Support.

Questions?

Contact your PubMatic Account Manager. 
Ad Server Configuration for OpenWrap and SDKThis step is required so the GAM ad server, based on actual bid price, can allocate impressions to the winning partner. See GAM Ad Server Configuration (for OpenWrap and SDK).
Ad Server SDK

You must integrate the  Google Mobile Ads SDK (typically referred to as simply, GAM  or its former abbreviation  DFP , throughout this documentation), to work with the OpenWrap SDK.

Integrate Google Mobile Ads SDK (GAM)

Before you start integrating the PubMatic OpenWrap SDK, you must integrate the Google Mobile Ads SDK in your app. OpenWrap SDK has been tested and certified with GAM SDK version 8.3.0 - 8.11.0 ; see the OpenWrap and GAM compatibility matrix . OpenWrap SDK should work with newer versions of GAM, 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 Google Mobile Ads SDK Dependency
pod 'Google-Mobile-Ads-SDK'


Important:

If you are using Google Mobile Ads SDK version 7.42.0 or higher, update your project's info.plist as required.

Integrate OpenWrap SDK

Note

You must migrate your app to a later OpenWrap SDK 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.

Next integrate the PubMatic OpenWrap SDK and GAM event handlers in your application. The PubMatic's event handler for GAM is important as it makes the ad server call using GAM SDK APIs.

You can integrate these dependencies one of two ways: using CocoaPods or performing a manual integration. You'll find instructions for both below.

Integrate using CocoaPods

To ensure you're using the appropriate OpenWrap handler for your target GAM version, check the OpenWrap and GAM version compatibility matrix below.

OpenWrap and GAM compatibility matrix

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

How to read the matrix:

  • If you're using OpenWrap SDK v2.3.0 and want to use GAM SDK v8.3.0 – 8.11.0, use handler version 2.5.0.
  • If you're using OpenWrap SDK v1.9.0 and want to use GAM SDK v7.66.0 - v7.69.0, use handler version 1.4.0.
COMPATIBLE OW SDK VERSION(S)USE OW HANDLER VERSIONCOMPATIBLE GAM SDK VERSION(S)
2.3.02.5.08.3.0 - 8.11.0
2.2.02.4.08.3.0 – 8.8.0
2.1.02.3.08.3.0 – 8.8.0  
1.9.01.4.07.66.0 - 7.69.0

Follow these steps to integrate using CocoaPods: 

DoubleClick for Publishers (DFP) has been rebranded as Google Ad Manager (GAM), but you should continue to use DFP in your code.

Step 1: Add the following lines in the Podfile.

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

The Podfile should now look similar to this:

Example Podfile
platform :ios, '10.0'

target 'SampleApp' do
    pod 'Google-Mobile-Ads-SDK'
    pod 'OpenWrapSDK'
    pod 'OpenWrapHandlerDFP'
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 handlers. Check this compatibility matrix to make sure you select the correct handler for your target GAM version:

GAM handler compatibility matrix

Other handler downloads for manual integration

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

OpenWrap and GAM compatibility matrix

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

How to read the matrix:

  • If you're using OpenWrap SDK v2.3.0 and want to use GAM SDK v8.3.0 – 8.11.0, use handler version 2.5.0.
  • If you're using OpenWrap SDK v1.9.0 and want to use GAM SDK v7.66.0 - v7.69.0, use handler version 1.4.0.
COMPATIBLE OW SDK VERSION(S)USE OW HANDLER VERSIONCOMPATIBLE GAM SDK VERSION(S)
2.3.02.5.08.3.0 - 8.11.0
2.2.02.4.08.3.0 – 8.8.0
2.1.02.3.08.3.0 – 8.8.0  
1.9.01.4.07.66.0 - 7.69.0

Follow these steps to perform a manual integration:

Step 1. Download the OpenWrap SDK zip file.

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

Step 2. Next download the OpenWrap Handlers. 

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

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

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 security (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:

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 request App Tracking Transparency(ATT) authorization and 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.

Supported ad formats

Now that you've integrated the OpenWrap iOS SDK , you're ready to begin implementing ads in your app. OpenWrap iOS SDK currently supports two ad formats:

Banner :

Mobile banner ads usually appear as a short strip spanning the width of the app page or screen, positioned above or below the app content. Banner ads can be static or animated images, any mobile-compatible rich media ad format, or in-banner video.

Native and Banner:

Native ads are native assets rendered via an app's native UI components to provide a consistent visual design. Though OpenWrap SDK doesn't support native ads separately, you can combine native and banner requests to support native inventory through the SDK's header bidding feature.

Interstitial :

Mobile interstitial ads fill the screen or page and require the user to dismiss the ad before they can view/access the app's main content. Interstitial ads also support  static or animated full-screen images, any mobile-compatible rich media ad format, or full-screen video.

Rewarded :

Mobile rewarded ads fill the screen or page and require the user to dismiss the ad before they can view/access the app's main content. Rewarded ads support only full-screen video ad formats. Once video playback completes the user receives in-app rewards.

Table of Contents

⇧ Top

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