iOS SDK 4.1

SDK 4.1

Download the iOS SDK

Developing Your Application

Download the Conversant 4.1 SDK (formerly Greystripe SDK)

Unzip the IOSSDK4.1.0 folder.

The following files are packaged with the Conversant iOS SDK 4.1:

  • GSAd.h
  • GSAdDelegate.h
  • GSAdBannerAdView.h
  • GSConstants.h
  • GSFullscreenAd.h
  • GSLeaderboardAdView.h
  • GSMediumRectangleAdView.h
  • GSMobileBannerAdView.h
  • libGreystripeSDK.a

The Conversant SDK files once added to Xcode:

 

Xcode 4.5 Setup

Xcode 4.5 is required for Conversant's iOS SDK 4.1.0. Building with Xcode 4.4 and below will lead to compile errors. The Conversant SDK takes advantage of the latest APIs available from Apple.

Adding the SDK to your App

The easiest way to include the Conversant SDK into your project is to drag the IOSSDK4.1 folder from the Finder into the Project Navigator for your project. This directory contains our compiled library as well as all the necessary header files for importing our classes and protocols into your code.

Please note: If you’ve included a previous version of the Greystripe library (libGreystripeSDK.a), you may need to remove references to the old library in your Projects “Library Search Paths” setting in the Build Settings tab.

Required Frameworks

Before integrating Conversant calls into your code, you’ll need to include some shared Frameworks in your project.

  1. In the Project Navigator, select your project’s icon
  2. Select your target app under Targets
  3. Select the 'Build Phases' tab of the target
  4. Open 'Link Binaries With Libraries' expander
  5. Click the '+' button in the lower left of the expander
  6. Select the following Frameworks (if not already included in your project):
    • AddressBook.framework
    • AdSupport.framework *
    • CoreGraphics.framework
    • EventKit.framework
    • Foundation.framework
    • libsqlite3.dylib
    • libz.dylib
    • MessageUI.framework
    • MobileCoreServices.framework
    • QuartzCore.framework
    • SystemConfiguration.framework
    • UIKit.framework

* AdSupport.framework is required but set to “Optional” in Build Phases under the Link Binary with Libraries section so that you will not get errors when running your application on iOS devices with 5.x or lower.

 

Update Build Settings (Required for Banners in IB or Storyboard)

If you are implementing Banner Ads (320x50, 300x250 or 728x90 sizes) using Interface Builder or Storyboards, you need to add two linkers to the Build Settings. Note: This is not required for Fullscreen Ads.

  1. In the Project Navigator, select your project’s icon
  2. Select your target app under Targets
  3. Select the 'Build Settings' tab of the target
  4. Find the ‘Other Linker Flags’ setting
  5. Add two new lines to the Other Linker Flags: –all_load and –ObjC

 

Ad Objects

Conversant's 4.1 SDK uses a more object-oriented paradigm than our previous 3.x SDKs. All ads are instances of objects, and are constructed and controlled by the host app. There is no ad manager object or other global SDK object which needs to be initialized at app start-up. All interaction occurs with GSAd subclasses and their delegates.

Initializing Ads

All ads, both fullscreen interstitials and banners, inherit from the GSAd class and share a basic lifecycle. The first step is to create an instance of the GSAd subclass for the type of ad you want to show. Each size has its own subclass. For example, here is the constructor used on line 42 of the GSSDKDemo project’s iPhoneFullscreenViewController.m to initialize a fullscreen ad:

 self.myFullscreenAd = [[GSFullscreenAdView alloc]  initWithDelegate:self];

This constructor takes a single argument that is a delegate object implementing the GSAdDelegate protocol. In this example from the GSSDKDemo project included in the SDK zip, the delegate is set to the active view controller and the instance assigned to a property of that View Controller for later easy access.

Delegate Setup

Conversant's GSAdDelegate protocol defines a number of selectors which your delegate object can implement to simplify creation of ad instances. The delegate protocol also defines selectors for being notified about ad related events discussed later in this document.

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. The SDK allows you to identify your app to our server in the initialization for each ad instance. However, if you are creating multiple ad instances which will share a single delegate object, you can implement the protocol’s greystripeGUID selector. In the example project from the iPhoneViewController, we have included a Test GUID implemented via this delegate callback mechanism.

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 autoload property will cause the first ad to be fetched and loaded into your view hierarchy as soon as the view is created.

For banner type ads (all ads except fullscreen interstitials), you can override the first ad’s initial fetch and display process by implementing the delegate’s greystripeBannerAutoload selector to return FALSE. This means that the ad instance will be included in your view hierarchy but you will need to explicitly call the ad’s fetch selector when you want the ad to retrieved and displayed.

Displaying Fullscreen Ads

Unlike banner format ads, interstitial ads are not UIView types. 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 being fetched, fullscreen ads must call their displayFromViewController: selector 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.

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 the GSAd subclass you would like to use.

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

To see an example of this type of implementation, open the iPhone Storyboard in the GSSDKDemo project and select “Mobile Banner Ad View” element. You’ll see the size and custom class settings, and delegate Outlet you need in the Inspector.

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. Get an instance of the appropriate GSAd subclass
  2. Call the fetch selector of that instance
  3. Use the delegate callbacks described below, or the ad’s isAdReady 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 GSAdDelegate 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:

 greystripeAdFetchSucceeded:(id<GSAd>)a_ad

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:

 greystripeAdFetchFailed:(id<GSAd>)a_ad withError:(GSAdError)a_error

This passes a GSAdError, which is an enum type which indicates the cause of the failure. Please see the headers for the GSAdDelegate or this selector in the example project for the complete list of errors and their definitions.

User Events

When a banner ad is touched, we open a fullscreen in app browser. When this occurs the delegate’s greystripeWillPresentModalViewController 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:

 greystripeWillDismissModalViewController

followed by this message:

 greystripeDidDismissModalViewController

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.

iOS Mediation

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

No Thumb Builds and Unity 3D Support

For Unity 3D and other game engines that use ARM to compile instead of Thumb, we offer a special no-thumb build upon request.

Please contact Conversant support at [mailto:support_mobile@conversantmedia.com? support_mobile@conversantmedia.com] and ask for our no-thumb build.

The only difference for integrating the no-thumb build is the libGreystripeSDK.a file is compiled for ARM instead of Thumb. All other instructions above still apply.

Problems or Questions?

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.