Kiip iOS SDK

Overview

Read up on the various features and aspects of the Kiip iOS SDK. For a step-by-step guide, please check out the iOS Guide.

AppleDocs

For advanced integrations you may prefer browsing the complete set of auto-generated AppleDocs. If you have any questions about methods or classes mentioned and not outlined below please feel free to contact us.

Initialize

Once you register an iPhone app on our application dashboard, we’ll automatically generate an App Key and App Secret–keep them handy when you start the initialization process. In general, you should initialize within AppDelegates. You’ll need to import the Kiip library whenever you want to initialize.

The method to initialize the Kiip SDK takes the following parameters:

  • @param appKey (NSString): The applications key, provided by Kiip.
  • @param appSecret (NSString): The applications secret, provided by Kiip.
Kiip *kiip = [[Kiip alloc] initWithAppKey:@"app_key" andSecret:@"app_secret"];

Lifecycle

When you initialize your application, the KiipDelegate parameter added in your .h file will take care of managing moments. Something like below is all you’ll need:

@interface MyAppDelegate : UIResponder <UIApplicationDelegate, KiipDelegate>

Moments

When you save a moment with the SDK, it’s automatically registered with us on the dashboard. You will need to make sure the completionHandler is up and running, to handle error.

Save a moment

  • @param momentId (NSString): The unique identifier of the moment. This will dynamically create a moment for tracking in the Kiip system. This is an arbitrary name chosen by you.
  • @withCompletionHandler: A callback that must be created to show the poptart and handle errors.
[[Kiip sharedInstance] saveMoment:@"Beat Level One" withCompletionHandler:^(KPPoptart *poptart, NSError *error) {
if (error){
NSLog( @"something's wrong");
}
if (poptart){
[poptart show];
}
}];

Object Properties

The Kiip object allows you to attach user information automatically without user intervention. For example, if you already have a user’s e-mail, you can pre-populate a reward unit when you reward your users.

Object

Set the following properties on the Kiip sharedInstance.

Kiip *kiip = [Kiip sharedInstance];

Email

  • @property (NSString) *email Sets a user’s email address so it auto-populate’s in the reward.
kiip.email = @"support@kiip.me"

User ID

  • @property (NSString) *userId Sets a user’s user id for virtual currency rewards. Including it increases the potential revenue you can earn, as some rewards require it for delivery.
kiip.userId = @"304203"

Gender

  • @property (NSString) *gender Sets a user’s gender to help with targeting relevant rewards.
kiip.gender = @"Male"

Birthday

  • @property (NSDate) *birthday Sets a user’s birthday to help with targeting relevant rewards.
kiip.birthday = @"03/19/1990"

Poptart Overview

Poptart is the name of the entire reward workflow Kiip manages for you. By calling [poptart show] when you save a moment, Kiip enables the following routine to run:

saveMoment called > Poptart onShow > Modal onShow > Modal onDismiss > Poptart onDismiss

Event Listeners

Kiip’s SDK can notify you of events that occur, such as showing and hiding notifications. While saving a moment, on the [Kiip sharedInstance] class, you can set listeners for:

  • poptarts
  • notifications
  • modals
  • virtual currency

Poptarts : KPPoptartDelegate

KPPoptartDelegate is the overarching modal and notification system. The delegate can be accessed in the completion handler of a saveMoment call by doing:

[[Kiip sharedInstance] saveMoment: momentId withCompletionHandler:^(KPPoptart *poptart){

// setting the delegate before showing poptart
poptart.delegate = self;

// show poptart
[poptart show]

}];

Within the same file, you’ll have to then implement the listener. Something like the following will get you set up:

- (void)willPresentPoptart: (KPPoptart *) poptart {
NSLog( @"Can't wait for my poptart!");
}

The following methods can be implemented for the poptart delegate.

willPresentPoptart

Called before the poptart is presented to the user.

didDismissPoptart

Called after the poptart was dismissed.

Modals : KPModalDelegate

The KPModal is the fullscreen view of a Kiip reward. The delegate can be accessed in the completion handler of a saveMoment call by doing:

[[Kiip sharedInstance] saveMoment: momentId withCompletionHandler:^(KPPoptart *poptart){
// set notification delegate.
KPModal *modal = poptart.modal;
modal.delegate = self;

// show poptart
[poptart show]
}];

Like the poptart listeners, you’ll have to implement the modal listeners in the same file, something along the lines of:

- (void)willPresentModal: (KPModal *) modal {
NSLog( @"Here comes a reward!");
}

The following methods can be implemented for the Modal delegate:

didDismissModal

Called after the modal was dismissed, either by being closed or a reward being redeemed.

willPresentModal

Called before the modal is presented to the user.

Video

Starting with SDK 2.0.8, we’ve included video rewards to present to your user. In order to optimize the Kiip experience, we’ll notify you before a video is about to play, and when the video has ended (or if the user has chosen to close the video manually).

kiipVideoPlaybackDidBegin

Called right before a video will play. Usually used to mute volume in your app.

kiipVideoPlaybackDidEnd

Called right after a video is finished, or a user closes a video before it finishes. Resume background noise.

Virtual Currency Listener

This listener is called when a user has been rewarded virtual currency.

  • @param kiip: The Kiip instance.
  • @param content (NSString): The identifier of the content that should be awarded to the user.
  • @param quantity (int): The amount of content that should be awarded to the user.
  • @param transactionID (NSString): The unique identifier of this transaction.
  • @param signature (NSString): The signature that can be checked against the Kiip API to validate this transaction.
- (void) kiip:(Kiip *)kiip didReceiveContent:(NSString *)contentId quantity:(int)quantity transactionId:(NSString *)transactionId signature:(NSString *)signature {
// Give the currency to the user.
}

Reward Redemption Callback URL

If you choose to validate a reward redemption, you may via a server callback. First you will have to set up a callback URL. This requires creating an endpoint on an accessible server.

Currently, the reward redemption callback URL may only be used with virtual currency reward redemptions.

Virtual Currency Reward Redemption Callback URL (optional)

The callback URL can be used to verify a virtual currency reward redemption. This callback does require a userId be set on the Kiip object.

The POST request will contain the following data:

  • content (string): The unique identifier of the virtual currency (e.g. coins, only used for virtual currency rewards)
  • quantity (int): The quantity of the virtual currency (e.g. 20, only used for virtual currency rewards)
  • user_id (string): A unique field in which to verify the user. This could be any unique identifier, be it a login handle, email address or Advertising ID. This is required if using the virtual currency reward redemption callback.
  • transaction_id (string): The unique reward transaction ID.
  • signature (string): The signed signature of the payload. Used to verify valid posts. See below for more information.

Verify a virtual currency callback using this string containing the following:

sha1(content + quantity + user_id + transaction_id + app_secret)

Here’s a quick example of how you would verify the request in python:

def is_valid_request(content, quantity, user_id, transaction_id, signature):
    sign = '%s%s%s%s%s' % (content, quantity, user_id, transaction_id, YOUR_APPLICATION_SECRET)
    return hashlib.sha1(sign).hexdigest() == signature

Custom Notifications

The Kiip SDK allows you to attach your own assets when you show a notification view. This promotes a higher level of immersion for your app’s UX. Step one is to ensure you are saving moments correctly. Once that’s taken care of, navigate to your saveMoment callback.

You’ll want to start by listening in on the poptart.onShow method. Once that’s taken care of, you can begin to construct your own notification view, and attach it to the poptart:

// within poptart.onShow
// create your custom notification.

[poptart setNotification:( /* your customly created notification */ )];

Example

Check out the notification below to get an idea of what a custom notification can look like (You earned a reward! section):

Example reward

Note: There is more than one right way of implementing custom notifications.