App SDK - iOS

Conversant also offers a server-to-server integration option for apps via certain mediation partners. Please see our Integrate reference page to learn more.

SDK Integration Overview

The Conversant iOS SDK provides a simple way to monetize your iOS applications via in-application ads. Once integrated with the iOS SDK, your application will communicate with Conversant’s Ad Network to retrieve and display ads. Conversant handles all ad sales, both in the US and internationally, and provides comprehensive back-end accounting and reporting.

Setup and Enrollment

You should have already signed up through Conversant’s developer website and registered the apps you plan to monetize. For each app registered, you are given an app ID which can be found with the following steps here.

Please note that it may take some time before your registration and IDs are available. During this period you can use the testing IDs and process from our Testing page.

Supported Devices, OS and Ad Sizes

Conversant's iOS SDK 5.0 supports iPhone, iPod touch and iPad devices running iOS 8.0 and above.

Our SDK features two types of ads: Banner Ads and Interstitial Ads. Banner ads are displayed alongside your content, while Interstitial Ads appear as fullscreen ads when you choose to present them.

Visit our Technical FAQ for a detailed matrix of ad sizes and the iOS devices.

SDK Builds

Due to limitations of swift frameworks, there are three version available: device, simulator, and universal. For testing purposes, we recommend using the universal build. When you are ready to submit to the App Store, use the device build.


iOS SDK 5.0 Integration Guide

Step 1 - Download the iOS SDK

  1. Download the Conversant iOS SDK from our GitHub page, clone the repository to your computer using Git or download directly.

  2. Review the latest releases notes.

  3. Navigate to the file location the unzipped/cloned files on your computer.

    In addition to the license and readme files, there are three folders:

    • Release-iphoneos: this contains the build to use for upload to the App Store.
    • Release-iphonesimulator: this contains the build to use for simulator testing.
    • Release-iphoneuniversal: this contains the build to use for simulator and device testing.
    • ConversantSDKSampleAppSwift: this contains a swift sample app that shows how to integrate the various types of ads.
    • ConversantSDKSampleAppObjC: this contains an Objective C sample app that shows how to integrate the various types of ads.

Step 2 - Add the Conversant SDK to your Xcode project

  1. Start Xcode and open the iOS project you wish to integrate Conversant with.

  2. If you previously had an earlier Conversant SDK installed, remove this older version from your project before adding the new version.

    In the Xcode Project Navigator:

    • If the SDK is in its own Xcode file group, select the group.
    • If the SDK is not in its own file group, select the old Conversant SDK files in the Xcode file navigator.
    • Right click and click "Delete".
    • When prompted, choose "Remove References".
    • Verify that the SDK files have been removed.

    Please note: You may need to also remove references to the old library in your Projects “Library Search Paths” setting in the Build Settings tab.

  3. Right click on your Xcode project name in the Project Navigator and choose "New Group"

  4. Name the group "Conversant SDK 5.0" or a name of your choosing

  5. Right click on the newly created group and choose "Add Files to [Project Name]..."

  6. Navigate to the relevant build folder and add the framework to your project. The framework will be named ConversantSDK.framework.

  7. Confirm the framework has been added to your project.

  8. Navigate to your Project in the Project Navigator and then add the framework under "Embedded Binaries". The ConversantSDK.framework will appear under embedded binaries AND linked binaries.

Step 3 - Configure Xcode project settings

This is only a requirement for Objective-C projects.

Navigate to build settings and ensure Always Embed Swift Standard Libraries is set to yes. This defaults to no in new projects.

Step 4 - Integrate Common Conversant SDK Code

Both banner and interstitial ads require a common SDK code base. This is to be added in your App Delegate.

In addition, each application must have a unique application identifier (aka the App ID or GUID).

Identifying Your App

In order to allocate ads to your application and credit you for payment, the SDK needs to provide an App Id (aka a “GUID”). As described in the Setup section, you will need to register on our developer portal to obtain a GUID for each application you plan to launch with Conversant.

Swift/Objective-C

@import ConversantSDK 

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

       // Your code.

       ConversantConfiguration.defaultConfiguration.applicationId = "MyConversantApplicationID"
       
       // Your code.
       return true

   }

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // your code.

    ConversantConfiguration.defaultConfiguration.applicationId = @"My Conversant Application ID";


    // your code.
    return YES;

}

Location Data

Starting with version 5.0, the Conversant SDK will automatically use location data if your app has permission from the user. No settings are required for this to work.

Now that the SDK files, Xcode setup and common code have been setup in your Xcode project, decide which ad size or sizes to add to your iOS project and where to add them logically for your application.

Step 5 - Displaying Interstitial Ads

Fullscreen ads take over the entire screen of the device and must be dismissed by the user, similar to the modal view controller paradigm used by iOS.

After an ad has successfully been fetched, you must call the fullscreen ad's present(from:) function explicitly. We recommend you do this when you reach a natural juncture in your app’s user experience (such as between levels of a game or after viewing an article in a news app). This selector acts like a modal controller so you will need to provide a view controller instance as it’s single argument. This should be the active view controller when you want the interstitial to be displayed as it will be used for the animation transition from your app to our fullscreen ad display.

Swift

import UIKit
import ConversantSDK

class ViewController: UIViewController, ConversantInterstitialAdDelegate {


    @IBAction func loadAd () {
        let interstitialAd = ConversantInterstitialAd(delegate: self)
        interstitialAd.fetch()
    }

    func interstitialAdLoadComplete(ad: ConversantInterstitialAd) {
        ad.present(from: self)
    }

    func interstitialAdLoadFailed(ad: ConversantInterstitialAd, error: ConversantError) {
        let alert = UIAlertController(title: "Failed", message: "Ad Load Failed with error: (error.description)", preferredStyle: .alert)
        let ok = UIAlertAction(title: "OK", style: .default) { (_) in
            alert.dismiss(animated: true, completion: nil)
        }
        alert.addAction(ok)
        present(alert, animated: true, completion: nil)
    }

}

Objective-C

@implementation ViewController

- (IBAction)loadAd:(id)sender {
    ConversantInterstitialAd *ad = [[ConversantInterstitialAd alloc] initWithDelegate: self];
    [ad fetch];
}

- (void)interstitialAdLoadFailedWithAd:(ConversantInterstitialAd *)ad error:(ConversantError *)error {
    UIAlertController *alert = [UIAlertController alertControllerWithTitle:@"Oops" message:[NSString stringWithFormat:@"Loading failed with error %@", error.description] preferredStyle:UIAlertControllerStyleAlert];
    UIAlertAction *ok = [UIAlertAction actionWithTitle:@"OK" style:UIAlertActionStyleDefault handler:^(UIAlertAction * _Nonnull action)       {
        [alert dismissViewControllerAnimated:true completion:NULL];
    }];
    [alert addAction:ok];
    [self presentViewController:alert animated:YES completion: nil];
}

- (void)interstitialAdLoadCompleteWithAd:(ConversantInterstitialAd *)ad {
    [ad presentFrom:self];

}
@end

Delegate Methods

Interstitial Ads have five delegate methods, two of which are shown above (loadFailed and loadComplete). All delegate methods return the ad, so you don't need to have a property in your view controllers. There are three more delegate methods: * interstitialAdWillAppear: called directly before the ad will be presented. * interstitialAdWillDisappear: called before the ad will be dismissed. * interstitialAdDidDisappear: called after the ad has been dismissed. Using these, you can control the flow of your app. You may wish to unpause your game, for example. You may also wish to load your next ad.

About Banner Ads

Banner Ads now auto-detect their size. You can create them either programmatically or with the interface builder.

Adding Banners in Interface Builder

If you are building your UI using XCode’s Interface Builder system, you can easily add our banner ad views to your interface. Start by including a generic View of the appropriate size in your layout. Select the view object in your layout and open the Identity Inspector. Then, under the “Custom Class”, select "ConversantAdView" and under Module, select "ConversantSDK". In some versions of x-code, you may need to type these in manually. You will also need to assign the ad’s delegate in Interface Builder. To do so, you can open the Connections Inspector. Then, under Outlets, select delegate and add the object you are using as your ad delegate (usually the ViewController for interface where the ad will be shown). If you are unable to connect this in the storyboard, you may assign the delegate in the viewDidLoad implementation of your app.

Adding Banners Programmatically

The SDK also allows you to create and integrate ad instances into your view hierarchy programmatically. After creating the ad instance, you should call the ad’s fetch selector. If the fetch succeeds, add the instance to your view hierarchy. If the fetch fails, you can use the delegate selectors below to determine why the fetch failed, or simply move on to another ad network or back-up image.

The basic flow of managing a banner can be summarized as: 1. Initialize the ConversantAdView using one of the initializers. a. Initialize with an adFormat and a Delegate. b. Initialize with a frame and a delegate. c. Initialize with a frame. d. Initialize with a frame, configuration, and delegate. 2. Call the fetch selector of that instance. 3. Use the delegate callbacks described below, or the ad’s isReady selector to determine if an ad has been successfully retrieved. 4. If the fetch has succeeded, place the ad in the view hierarchy. 5. To show a new ad in the same position, again call the ad’s fetch selector.

Refreshing Banners

Once an ad instance has been created and you would like to “refresh” the ad to show another ad in that position, you can call the fetch selector. If the ad view is in the view hierarchy, the displayed ad will refresh as soon as the ad is successfully fetched. If the ad is not visible, the newly fetched ad will be cached locally until it is re-added to the screen. We recommend you refresh the ad no more frequently than every 5 seconds. Very frequent fetch attempts will likely result in no ad being returned by our server.

Placing Banners

Our ad classes can be placed anywhere on screen using the standard UIView frame, origin, and center properties. However, ads cannot be resized and any changes to the height or width of the ad instance will disable the ad from showing, and no impressions or clicks for the ad will be counted.

Delegate Events

During the course of the ad lifecycle, there are a number of events that your app should be aware of and respond to. When your ad instance is created, you provide a delegate object that should implement the selectors of the ConversantBannerAdDelegate protocol you’ll need to track and respond to these events.

Fetch Events and Errors

The ad’s delegate can implement call-backs to be notified when ads have been successfully fetched and are ready to be shown. In particular you can implement this selector:

bannerAdLoadComplete(ad:ConversantAdView)

Since the delegate may be shared across instances, the pointer is passed as the argument to this selector. You can then use the passed value to check which ad instance is ready to be displayed. In the case that an ad’s fetch request fails, we provide a protocol selector:

bannerAdLoadFailed(ad:ConversantAdView, error:ConversantError)

You can use error.description to determine what the error was.

User Events

When a banner ad is touched, we open a fullscreen in app browser. When this occurs the delegate’s bannerAdWillPresentScreen(ad:ConversantAdView) is called. You should use this selector to pause any animation, video or sound. While our click-through browser is open you should also avoid any intensive network activity or changes to the active view controller or UIWindow. Pushing or popping a new view controller, presenting an alert view, and other UI actions that occur while our fullscreen window are open may result in exceptions or undefined behavior. Once the user is done with the in app browser the delegate will receive this message:

bannerAdWillDismissScreen(ad:ConversantAdView)

followed by this message:

bannerAdDidDismissScreen(ad:ConversantAdView)

You can use these to resume your apps normal activity and refresh the displayed ad. Banner ads that have been clicked on may still be visible and clickable when the user returns from the click-through modal. It is up to your app to either refresh or remove the banner, and additional clicks by users will not be credited for payment.

Autoload Ads

Once an ad instance is initialized, you will need to request an ad from the Conversant server. In order to ensure a smooth end-user experience, Conversant ads must be fetched prior to display. In cases where the ad is included using interface builder, the banner’s configuration.autoLoad property will cause the first ad to be fetched and loaded into your view hierarchy as soon as the view is drawn. The configurations autoDisplay will then display the ad once it is fetched. This means that you can simply a banner ad in interface builder and the ad will automatically load and display. You can change this behavior by changing ConversantConfiguration.defaultConfiguration.autoLoad and ConversantConfiguration.defaultConfiguration.autoDisplay to the desired values. Ads that are created programmatically will also load automatically and display automatically once added to a visible view hierarchy.

iOS Mediation

Conversant's iOS SDK is integrated with a number of leading mediation layers. Please visit the Mediation page for more details.

Support

If you encounter any problems during integration please try the Testing process described on our Testing page. If your problem persists, please check the Troubleshooting page for information about common pitfalls and known issues.

If you have other questions or concerns please review our Technical FAQ and our Business Information pages.