Kiip iOS Integration Guide

Introduction

This guide will walk you through adding Kiip Rewards to your iOS application. Once you’re done, navigate over to the SDK Docs for extra, optional information.

Getting Started

First, make sure you’re registered for a developer account at app.kiip.me. Adding an app to your developer account will issue an app key and secret necessary to integrate the Kiip SDK.

Download the Kiip SDK

The latest Kiip SDK is always downloadable from the downloads page.

Add Yourself as a Test Device

There are two ways to set Test Mode using the Kiip SDK.

1. Setting Test Mode at the build level

This Test Mode method requires Kiip SDK 2.3.0 or higher. To set Test Mode at the build level requires include the follow flag:

@property (assign, nonatomic) BOOL testMode

The default value for this flag is NO.

2. Setting Test Mode at the device level

If using this method, we recommend adding a test device to your app before getting started with integrating Kiip. However, you can add a test device in the Kiip dashboard at any time.

To add a test device to an iOS app, click the Test Devices button at the bottom of the desired application page on the Kiip Dashboard. Define a unique name for the device and the device’s Advertising ID. You can retrieve your Advertising ID by downloading The Identifiers app.

For pre-iOS 7 devices, substitute the device’s MAC address for Advertising ID.

test device ios

Note: The iOS Simulator will always be recognized as a test device.

Common Testing Questions

What if I’m not in the US? How do I see a Kiip reward?

Test rewards fill 100% of the time, regardless of location. It is important that you add the correct device identifier inside the Test Devices section.

A null poptart? No test reward? Some devices work but others don’t!

If you’re getting a null poptart, don’t worry. This means you have correctly saved a moment through the SDK, but we didn’t recognize your device as a test device. Try the following techniques:

  • Ensure limited ad tracking is disabled in Settings.
  • Ensure you have copied and pasted the Google advertising identifier correctly (with dashes).

Integrate Kiip

Add the Necessary Frameworks

Before Kiip can load within your app, you’ll need to verify you can link the following frameworks below.

  1. Drag-drop KiipSDK.framework and KiipSDKResources.bundle into your XCode project.

  2. In Build Phases, verify that KiipSDK.framework is in the Link Binary with Libraries and the KiipSDKResources.bundle is in Copy Bundle Resources section.

  3. Open your projects Build Phases section and add in the following frameworks:

    • CoreTelephony.framework
    • QuartzCore.framework
    • SystemConfiguration.framework
    • AdSupport.framework
    • Passkit.framework
    • MediaPlayer.framework SDK version 2.0.8 and above

Note: Kiip iOS SDK 2.3.0 and above requires XCode 7 becuase of bitcode support. They are not compatible with XCode 6 or below. If you are using XCode 6 or below, download Kiip iOS SDK 2.1.1

Changes for iOS 9

Apple has changed its policies regarding TLS versions and only accepts connections which support TLSv1.2 SSL (iOS 9 and OSX 10.11). Developers will need to override this restriction by adding the following lines to the app’s Info.plist file

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

Intialize Kiip

Once you verify you’ve successfully linked the Kiip framework in your project, navigate to your AppDelegate.h. You will need the following import:

#import <KiipSDK/KiipSDK.h>

Note: You will need to import the library whenever you want to use a Kiip SDK function.

Then, add an interface for the KiipDelegate in your AppDelegate.h file.

@interface AppDelegate : UIResponder <UIApplicationDelegate, KiipDelegate>

Now, you can initialize Kiip in the didFinishLaunchingWithOptions method, located in AppDelegate.m.

It should look something like this:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    Kiip *kiip = [[Kiip alloc] initWithAppKey:@"app_key" andSecret:@"app_secret"];
    kiip.delegate = self;
    [Kiip setSharedInstance:kiip];
    return YES;
}

Make sure you replace your app_key and app_secret with your actual application key and secret, available on the Kiip dashboard.

Call a Kiip Moment

Kiip moments are points in your Application where you want to reward your user. The end user is allowed to earn rewards multiple times for the same moment. If there is a reward available, the SDK will display the reward to the user.

Locate the file you want to call your Kiip moment, and make sure you import Kiip:

#import <KiipSDK/KiipSDK.h>

Then, when you want to give a reward to a user, call a moment:

[[Kiip sharedInstance] saveMoment:@"Finishing Level One!" withCompletionHandler:^(KPPoptart *poptart, NSError *error) {
    if (error) {
        NSLog(@"something's wrong");
        // handle with an Alert dialog.
    }
    if (poptart) {
        NSLog(@"Successful moment save. Showing reward.");
        [poptart show];
    }
    // handle case with no reward available.
    if (!poptart) {
        NSLog(@"Successful moment save but no reward available.");
    }
}];

With one call, you’ve let the SDK know that you’d like to show a reward. Through the completion handler, you can also handle other logic, such as lowering the app’s volume.

Moment Names

Something to consider is how you name each moment. When you pass a string to the saveMoment call, such as “finishing level one”, it will be displayed to the end user when your app goes live – unless you change your moment names on your dashboard. The string the reward unit provides is: “Congratulations! Here’s a reward for [your moment name]”.

You can always edit your moment titles later on in the dashboard.

Reward Virtual Currency

If your app provides virtual currency, then you can reward your users with that, as well.

First, you’ll need to enable virtual currency rewards in the dashboard, and assign values to each dollar amount.

Then, place the following listener in your AppDelegate.m in order to listen for currency rewards.

- (void) kiip:(Kiip *)kiip didReceiveContent:(NSString *)contentId quantity:(int)quantity transactionId:(NSString *)transactionId signature:(NSString *)signature {
    // Give the currency to the user by using your in-app currency management.
}

This listener will be called by the Kiip SDK after a user redeems a reward that carries a virtual currency value, and we will pass a quantity of currency into the method under the quantity parameter. You can then handle depositing the value via your in-game currency management.

If a user chooses not to redeem currency, then the value passed down will be zero.

Rewarded Video

Access more inventory, increase engagement and drive more revenue with Rewarded Video. For access to Rewarded Video inventory please contact success@kiip.me.

Sample Application

We’ve provided a couple of sample applications for you to browse. Check out our public Github repo in case you’d like to try custom notifications, or just need to see some code-samples.

Need Help?

We’re happy to answer any questions about integrating Kiip. Check out our FAQ or email us.