Getting Started

Document created by david.simerly on Oct 19, 2017Last modified by david.simerly on Apr 3, 2018
Version 28Show Document
  • View in full screen mode

PubMatic SDKs 

PubMatic iOS SDK 

➤ Getting Started

Integrating Banner Ads

Integrating Interstitial Ads

Rich Media (MRAID 2.0) Support

Integrating Native Ads

Header Bidding With DFP

Passing Targeting Information

SDK Debugging


PubMatic iOS SDK Reference 

This Getting Started guide walks you through everything you need to get started with the PubMatic iOS SDK, beginning with the prerequisites for a successful integration.

 

Prerequisites

PubMatic iOS SDK requires the following:

  • iOS version 9 or greater.
  • Xcode 8 or greater.
  • PubMatic ad tag information (Publisher ID, Site ID, Ad ID). You'll find these values through the PubMatic platform. Contact your PubMatic Account Manager for more information.

 

Integrating PubMatic SDK

Integrate PubMatic iOS SDK in your app using one of the following methods:

 

 

The PubMatic SDK can be easliy integrated using Cocoapods, very popular dependency management system for iOS projects. To integrate the PubMatic SDK into your project using Cocoapods, add the following line to your project's Podfile:

   pod 'PubMaticSDK' 

 

The setup above installs all Supported Ad formats.

 

If your app doesn't require all ad formats, then you can choose just the formats you need. PubMatic iOS SDK is modular, so you can include or exclude the combination of ad format dependencies your app requires. Choosing only what your app will use also reduces your app's file size. Add one or more of the ad formats needed from the list below into your Podfile to customize which ad formats are installed:

 

# Integrate only Banner (with MRAID support)
pod 'PubMaticSDK/BannerAds'

# Integrate only Interstitial (with MRAID support)
pod 'PubMaticSDK/InterstitialAds'

# Integrate only Native Ad
pod 'PubMaticSDK/NativeAds'

# Integrate Header bidding for Banner and Interstitial
pod 'PubMaticSDK/HB'

# Integrate only Banner header bidding
pod 'PubMaticSDK/HB/Banner'

# Integrate only Interstitial header bidding
pod 'PubMaticSDK/HB/Interstitial'

 

Once your Podfile is setup the way you want, install PubMaticSDK pod with the command:

 

pod install

 

This completes PubMatic iOS SDK integration using Cocoapods. Skip the next two sections and continue with App Level Configuration > Other Linker Flags ⤵

 

Direct Source Code

To integrate the PubMatic SDK as source code within your app:

  1. Download the PubMatic iOS SDK code from the GitHub archives.
  2. Drag the <DOWNLOADS_FOLDER>/PubMatic-iOS-SDK/PubMaticSDK/PubMaticSDK folder into your app structure in Xcode as shown in Figure 1:

    imageFigure 1: Drag the PubMaticSDK folder into your app's structure in Xcode

  3. Configure the Choose options for adding the files dialog as shown in Figure 2:

    imageFigure 2: Configure the Choose options for adding the files dialog

  4. Choose Finish to close the dialog and save your configuration.

 

This completes your direct source code integration. Skip the next section and continue with App Level Configuration ⤵

 

PubMatic SDK Framework

This installation option references a pre-built SDK framework package that lets you build and reuse the framework package without having to reference the SDK source. To build and reference the framework package:

 

  1. Open the SDK source.
  2. Build the Framework target for an iOS Device destination. This produces the PubMaticSDK.framework package in the <DOWNLOADS_FOLDER>/PubMatic-iOS-SDK/PubMaticSDK/Products folder of the SDK source package.
  3. Drag PubMaticSDK.framework to the desired destination in your Xcode project as shown in Figure 1:

    imageFigure 1: Drag the PubMaticSDK folder into your app's structure in Xcode

  4. Configure the Choose options for adding the files dialog as shown in Figure 2:

    imageFigure 2: Configure the Choose options for adding the files dialog

  5. Choose Finish to close the dialog and save your configuration.

  6. Optionally, add PubMaticSDK.framework in the Build Phases > Link Binary With Libraries section if it wasn't automatically added in step 3. Then set Build Settings > Framework Search Paths to PubMaticSDK.framework.

 

This completes PubMatic SDK Framework integration. Continue with the next section, App Level Configuration ⤵

 

App Level Configuration

The PubMatic iOS SDK leverages several iOS frameworks, which requires the target to reference these frameworks. The following sections describe how to set up your app to meet these requirements.

 

Required Frameworks

PubMatic iOS SDK requires the following frameworks:

 

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

 

Other Linker Flags

Add –ObjC to Other Linker Flags of your application target's build setting as described below:

 

  1. In Xcode project navigator, press the blue top-level project icon.
  2. Select your target, then select the Build Settings tab.
  3. Under the Other Linker Flags section, add –ObjC to both Debug and Release.

 

Using Description Keys

To protect user privacy, any iOS app built after iOS 10 that also accesses any of the features described below, must statically declare the intent to do so. So before integrating any ad formats with your application, make sure you have added the appropriate keys to your app's Info.plist file to access required features from SDK.

 

If your app does not use any of the features below, but you include these keys in your Info.plist file only for ads, then your app will still prompt the user to authorize the features governed by the included keys.

                             

 

Most of the following keys are not mandatory. If any of these keys are not included in your app's Info.plist file, the corresponding feature will not work, but PubMatic SDK ensures that your app won't exit/crash.

 

Automatically detecting location

<key>NSLocationWhenInUseUsageDescription</key>
<string>#string in context of your app</string>

 

Location usage key is required in iOS 9.

 

Allowing calendar access

<key>NSCalendarsUsageDescription</key>
<string>#string in context of your app</string>

 

Allowing photo library access

<key>NSPhotoLibraryUsageDescription</key>
<string>#string in context of your app </string>

 

App Transport Security support (ATS)

As of iOS 9 and greater, non-HTTPs calls are blocked by default. To show ads using PubMatic iOS SDK, include the following entry in the application's Info.plist file:

 

<key>NSAppTransportSecurity</key>
<dict><key>NSAllowsArbitraryLoads</key><true/>
</dict>

 

Swift Support

You can integrate PubMatic iOS SDK in a Swift-based project using an Objective-C bridging header. Refer to Using Swift with Cocoa and Objective-C for details. Also see the SampleInSwift app (Written in Swift version 3.2 and Compatible with Swift 4.0), included in the PubMatic SDK bundle.

 

Attachments

    Outcomes