Kiip Integration in iOS

Kiip Integration in iOS

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. There are two ways to save a moment.

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];
    }
}];

Save a moment with a value

• @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.
• @param value (double): This is checked against a threshold (high or low) set in the Kiip dashboard. A user will only be rewarded if they reach the threshold, or fall below it if you’ve selected inverse.
• @withCompletionHandler: A callback that must be created to show the poptart and handle errors.

[[Kiip sharedInstance] saveMoment:@"Test High Score" value:5.0 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 Set’s a user’s email address so it auto-populate’s in the reward.

kiip.email = @"support@kiip.me"

Gender

• @property (NSString) *gender Set’s a user’s gender to help with targeting relevant rewards.

kiip.gender = @"Male"

Birthday

• @property (NSDate) *birthday Set’s 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.
}

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.

After proper error checking, look at the following section within the withCompletionHandler:

    // currently inside the withCompletionHandler
    if (poptart){
    
    // Set your rect coordinates and properties as you wish.
    KPNotificationView *notificationView = [[KPNotificationView alloc] initWithFrame:CGRectMake(0,0,320,50)];
    notificationView.backgroundColor = [[UIColor yourChoiceOfColor]];
    
    // note, this kiip var comes from the Kiip sharedInstance you declared earlier.
    kiip.notificationView = notificationView  
    
    // Now that the view is constructed, let's allocate for the notification itself 
    // and assign it to poptart's notification to override it.  
    KPNotification *notification = [[KPNotification alloc] init]
    poptart.notification = notification;
    
    // Programmatically create your UIView
    // customView ...
    
    // Attach to notificationView
    [notificationView addSubview: customView]
    
    // Let's start poptart with our new notification! 
    notificationView.poptart = poptart;
    [poptart show];
}