iOS SDK Release Notes

iOS SDK Overview

The Greystripe 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 Greystripe’s Ad Network to retrieve and display ads. Greystripe handles all ad sales, both in the US and internationally, and provides comprehensive back-end accounting and reporting.

Please note that the following instructions apply to Greystripe iOS SDK v4.2.1.

Setup and Enrollment

You should already have signed up through Greystripe’s developer website and registered the apps you plan to ad-enable. 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.

Xcode 4.5+ Required

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

Supported Devices, OS and Ad Sizes

Greystripe's iOS SDK 4.2 supports iPhone, iPod touch and iPad devices running iOS 4.3 and above.

Our SDK features three banner ad sizes (320x50, 300x250 and 728x90) and a fullscreen interstitial (300x250, 320x480 and 768x1024).

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

iOS SDK Design Concepts

Greystripe’s 4.2 SDK uses an object-oriented paradigm. All ads are instances of objects that 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.

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:

Class SDK Filename Ad Type Ad Sizes
GSFullscreenAdView GSFullscreenAdView.h Interstitial Ads 300x250
320x480
768x1024
GSLeaderboardAdView GSLeaderboardAdView.h Banner Ads 728x90
GSMediumRectangleAdView GSMediumRectangleAdView.h Banner Ads 300x250
GSMobileBannerAdView GSMobileBannerAdView.h Banner Ads 320x50

For example, here is the constructor used 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, the delegate is set to the active view controller and the instance assigned to a property of that View Controller for later easy access.

Greystripe’s GSAdDelegate protocol (GSAdDelegate.h) defines a number of selectors which your delegate object can implement to simplify creation of ad instances for each ad class above. The delegate protocol also defines selectors for being notified about ad related events discussed later in this document.


iOS SDK 4.2 Integration Guide

Step 1 - Download the iOS SDK

  1. Visit Greystripe’s GitHub page.

  2. Download the Greystripe iOS SDK or clone the repository to your computer using Git.

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

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

    • "GSSDKDemo" contains a sample Xcode project with examples of how to integrate all Greystripe ad sizes
    • "GreystripeSDK" contains the iOS 4.2 SDK files
    • "GSSDKDocs" contains the navigational iOS documents in web form
    • "SDKExtras" contains the "no-thumb" compiled version of the libGreystripeSDK.a file

    In the GreystripeSDK folder, the files listed are used to request and display Greystripe ads on an iOS app:

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

    * Note: GSSDKInfo.h replaces GSConstants.h as of SDK 4.2. If you are updating from a previous 4.x SDK, please be sure to update your code and replace #import "GSConstants.h" with #import "GSSDKInfo.h"

Step 2 - Add the Greystripe SDK to your Xcode project

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

  2. If you previously had an earlier Greystripe 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 Greystripe 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 "Greystripe SDK 4.2" 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 unzipped GreystripeSDK folder and add the 9 files to your project

    iOS 4.2 Add Files

  7. Confirm the 9 files have been to your project

    The Greystripe SDK files once added to Xcode:

    iOS 4.2 Files in Xcode

Step 3 - Configure Xcode project settings

Now that the Greystripe iOS SDK has been added, we must configure additional settings within Xcode

Step 3a - Add iOS Frameworks required by the SDK

  1. Select the project name in the Project Navigator

  2. Select the project name under the "Targets" in the column to the right of the Project Navigator

  3. Select the "Build Phases" tab

  4. Click on the arrow to the left of "Link Binaries With Libraries" to expand the framework list

  5. Click the '+' button in the lower left of the expanded "Link Binaries With Libraries"

  6. Add the following Frameworks (if not already included in your project):

    iOS Framework Build Phase Setting iOS Developer Library Link
    AddressBook.framework Required AddressBook Reference
    AddressBookUI.framework Required AddressBookUI Reference
    AdSupport.framework Optional * AdSupport Reference
    CoreGraphics.framework Required CoreGraphics Reference
    CoreLocation.framework Required CoreLocation Reference
    EventKit.framework Required EventKit Reference
    EventKitUI.framework Required EventKitUI Reference
    libsqlite3.dylib Required
    libz.dylib Required
    MessageUI.framework Required MessageUI Reference
    MobileCoreServices.framework Required MobileCoreServices Reference
    PassKit.framework Optional * PassKit Reference
    QuartzCore.framework Required QuartzCore Reference
    Social.framework Optional * Social Reference
    StoreKit.framework Optional * StoreKit Reference
    SystemConfiguration.framework Required SystemConfiguration Reference
    Twitter.framework Optional * Twitter Reference
    UIKit.framework Required UIKit Reference

    * Note: The frameworks listed as “Optional” are still required by the SDK. Setting frameworks to "Optional" allows backward compatibility with versions of iOS that do not have that framework.

  7. Verify all frameworks have been added and configured correctly

    Here is how the required iOS frameworks look, once successfully added to Xcode:

    iOS 4.2 Frameworks

Step 3b - Configure additional 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. Select the project name in the Project Navigator

  2. Select the project name under the "Targets" in the column to the right of the Project Navigator

  3. Select the "Build Settings" tab

  4. Find the "Build Active Architecture Only setting" and select Yes from the dropdown.

  5. Find the "iOS Deployment Target" setting and ensure "iOS 4.3" or higher is selected from the dropdown.

  6. Find the "Other Linker Flags" setting

  7. Add the following to the Other Linker Flags (be sure to include the hyphen):

    • –ObjC

iOS 4.2 Other Linker Flags

Step 4 - Integrate common Greystripe SDK code

Both banner and interstitial ads require a common SDK code base. GSAdDelegate.h and GSDKInfo.h are required to request and receive ads, regardless of your ad size choices.

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

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.

Step 4a - Add the following code to your "ViewController.h" header file:

  1. Import "GSAdDelegate.h"

     #import "GSAdDelegate.h"
  2. Adopt the GSAdDelegate protocol

     @interface ViewController : UIViewController <GSAdDelegate>
  3. Add the NSString protocol for calling unique Greystripe App Id / GUID associated with your app

     - (NSString *)greystripeGUID;

Step 4b - Add the following code to your "ViewController.m" implementation file:

  1. Import "GSSDKInfo.h"

     #import "GSSDKInfo.h"
  2. Implement the App ID

    Option 1: Create an NSString locally and return the value

    - (NSString *)greystripeGUID 
    {
        NSString *guid = @"5f750a48-7e73-42e7-bede-839fda15f367";
        return guid;
    }

    Option 2: Define the App ID globally and return the value

    As seen in the GSSDKDemo app, one can also declare the GUID globally. In the SDK Demo app example, a Constants.h file can be created.

    #import <Foundation/Foundation.h>

    @interface NSObject ()

    // Greystripe SDK Test GUID
    #define GSGUID @"51d7ee3c-95fd-48d5-b648-c915209a00a5"

    @end

    In the YourAppName-Prefix.pch prefix header file, you can import the Constant.h file before the app delegate launches.

     #ifdef OBJC
         #import <UIKit/UIKit.h>
         #import <Foundation/Foundation.h>
         #import "Constants.h"
    #endif

    Once a global definition has been made, you can simply return the GSGUID value on any "ViewController.m" file

    - (NSString *)greystripeGUID 
    {
        return GSGUID;
    }

Step 4c - Optional. Pass accurate location based information

Starting with 4.2, if your application collects CoreLocation data, it can be passed along to Greystripe. The code below is an example implementation to help you get started. Real implementations will depend on many design decisions that are out of scope for the purposes of this page.

Add the following code to your AppDelegate.h file:
  1. Import <CoreLocation/CoreLocation.h> and GSAdDelegate.h

     #import <CoreLocation/CoreLocation.h>
    #import "GSAdDelegate.h"
  2. Adopt the CoreLocationDelegate protocol

    @interface AppDelegate : UIResponder <UIApplicationDelegate, CLLocationManagerDelegate>
  3. Declare an instance of CLLocation Manager

    @property (strong, nonatomic) CLLocationManager *locationManager;
Add the following code to your AppDelegate.m file:
  1. Import GSSDKInfo.h

     #import "GSSDKInfo.h"
  2. Synthesize the locationManager instance

     @synthesize locationManager;
  3. Add the following code in didFinishLaunchingWithOptions

    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        locationManager = [[CLLocationManager alloc] init];
        locationManager.delegate = self;
        [locationManager setDesiredAccuracy:kCLLocationAccuracyBest];
        [locationManager startUpdatingLocation];
       
        return YES;
    }
  4. Add the following code to retrieve location information

    - (void)locationManager:(CLLocationManager *)manager didUpdateToLocation:(CLLocation *)newLocation fromLocation:(CLLocation *)oldLocation {
       
        [GSSDKInfo updateLocation:newLocation];
    }

    - (void)locationManager:(CLLocationManager *)manager didFailWithError:(NSError *)error {

    }

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.

The code for banner ads is similar for 320x50, 300x250 and 728x90 sizes. However 728x90 leaderboards are only available for iPad and iPad mini.

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

Steps to display an interstitial ad:

Step 5a - Add the following code to your "ViewController.h" header file:

  1. Complete Step 4 and ensure all common SDK code has been added to the project

  2. Add @class GSFullscreenAd

     @class GSFullscreenAd;
  3. Declare an instance of GSFullscreenAd

     @property (strong, nonatomic) GSFullscreenAd* myFullscreenAd;

Step 5b - Add the following code to your "ViewController.m" implementation file:

  1. Import "GSFullscreenAd.h" and "GSSDKInfo.h"

     #import "GSFullscreenAd.h"
    #import "GSSDKInfo.h"
  2. Synthesize the myFullscreenAd instance

     @synthesize myFullscreenAd;
  3. Initialize the fullscreen ad object and set the delegate to the ViewController in viewDidLoad

    - (void)viewDidLoad 
    {
        [super viewDidLoad];
        // Do any additional setup after loading the view.

        self.myFullscreenAd = [[GSFullscreenAd alloc] initWithDelegate:self];
    }
  4. Add the ad fetch call that requests an ad from Greystripe

     [myFullscreenAd fetch];
  5. Call the display call on a successful ad request to display an ad

     [myFullscreenAd displayFromViewController:self];

Step 5c - Optional. Add Greystripe Interstitial delegate events

  1. Add the following code to your "ViewController.h" header file:

     - (void)greystripeAdFetchSucceeded:(id<GSAd>)a_ad;
    - (void)greystripeAdFetchFailed:(id<GSAd>)a_ad withError:(GSAdError)a_error;
    - (void)greystripeAdClickedThrough:(id<GSAd>)a_ad;
    - (void)greystripeWillPresentModalViewController;
    - (void)greystripeWillDismissModalViewController;
    - (void)greystripeDidDismissModalViewController;
  2. Add the following code to your "ViewController.h" header file:

    - (void)greystripeAdFetchSucceeded:(id<GSAd>)a_ad {
        if (a_ad == myFullscreenAd) {
            NSLog(@"Fullscreen ad successfully fetched.");
            // Add code on success
        }
    }

    - (void)greystripeAdFetchFailed:(id<GSAd>)a_ad withError:(GSAdError)a_error {
        NSString *errorString =  @"";
       
        switch(a_error) {
            case kGSNoNetwork:
                errorString = @"Error: No network connection available.";
                break;
            case kGSNoAd:
                errorString = @"Error: No ad available from server.";
                break;
            case kGSTimeout:
                errorString = @"Error: Fetch request timed out.";
                break;
            case kGSServerError:
                errorString = @"Error: Greystripe returned a server error.";
                break;
            case kGSInvalidApplicationIdentifier:
                errorString = @"Error: Invalid or missing application identifier.";
                break;
            case kGSAdExpired:
                errorString = @"Error: Previously fetched ad expired.";
                break;
            case kGSFetchLimitExceeded:
                errorString = @"Error: Too many requests too quickly.";
                break;
            case kGSUnknown:
                errorString = @"Error: An unknown error has occurred.";
                break;
            default:
                errorString = @"An invalid error code was returned. Thats really bad!";
        }
        NSLog(@"Greystripe failed with error: %@",errorString);
    }

    The delegate methods - (void)greystripeAdFetchSucceeded:(id)a_ad and - (void)greystripeAdFetchFailed:(id)a_ad withError:(GSAdError)a_error can inform your application of when an ad has been requested with success or if there was no fill for that particular request. If there is no fill on an ad request, Greystripe recommends waiting 30 seconds before calling for another Greystripe ad, or if mediated, rolling over to the appropriate next ad network.

    - (void)greystripeAdClickedThrough:(id<GSAd>)a_ad {
        NSLog(@"Greystripe ad was clicked.");
    }
    - (void)greystripeWillPresentModalViewController {
        NSLog(@"Greystripe opening fullscreen.");
    }
    - (void)greystripeWillDismissModalViewController {
        NSLog(@"Greystripe will close fullscreen.");
    }
    - (void)greystripeDidDismissModalViewController {
        NSLog(@"Greystripe closed fullscreen.");
    }

The delegate methods - (void)greystripeWillPresentModalViewController, - (void)greystripeWillDismissModalViewController and - (void)greystripeDidDismissModalViewController are useful for stopping or starting certain features in your application. If your app is a game has background music, you can pause the music on WillPresent and resume it on DidDismiss.

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.

Autoload Ads

Once an ad instance is initialized, you will need to request an ad from the Greystripe server. In order to ensure a smooth end-user experience, Greystripe 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.

iOS Mediation

Greystripe's iOS SDK is integrated with a number of leading mediation layers. Please visit the Mediation 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 Greystripe support at support@greystripe.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.