cjbeauchamp edited this page Aug 26, 2014 · 13 revisions

Getting started is easy, and as with Kii's cloud SDKs - the methods and classes are simple and powerful so you can implement using only a few lines of code.

If you're looking for class references, open docs/html/index.html from the repository.


In order to successfully follow the setup, you must have the following:

  1. Apple's developer tools for iOS
  2. A Kii Developer Account
  3. A Kii application provisioned
  4. Kii's Cloud SDK added to your application
  5. Kii's Analytics SDK added to your application

Portal Configuration

Activate Kii Referral

In order to utilize this Kii Labs feature, you must first activate it. To do so, follow these steps:

  1. Log into developer.kii.com
  2. Navigate to the app you wish to add this functionality to
  3. Click on the Labs tab on the left-hand side
  4. Select the KiiReferral tab on the top
  5. Click the Activate button

Add your app's Apple ID

When the links your users generate are clicked, they are taken to the iTunes Store in order to download your application. In order for this to work, you must add your app's Apple ID (found in iTunes Connect) to the Kii Referral portal.

Set up your default messaging

When your users open the share screen, the message that will be sent to their networks is pre-filled with some text - which is configurable via the default messaging pane as shown below:

Adding message configurations

If you wish to add alternate messaging based on the user status or flow of your app, you can set up alternate configuration keys with associated messages as shown below:

To learn how to utilize these within the SDK, check out the Custom Configuration Key code section.

Creating campaigns

As a developer, you may wish to track a campaign on social media to find out the effectiveness of your message. Create campaigns using the form as shown below and receive a shortened link that will track clicks and referrals.

Adding the Library

To add the library to your project, simply download the repository associated with this GitHub page and drag the items contained in the includes directory into your project. Ensure the following:

  • The framework is added to the 'Link Binary With Libraries' section of your app's build phases
  • The bundle is included in the 'Copy Bundle Resources' section of your app's build phases


Initialize the library

This can be placed directly after your Kii and KiiAnalytics initialization code in your project's AppDelegate.m file as shown:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
	NSString *appID = @"MY_KII_APP_ID";
	NSString *appKey = @"MY_KII_APP_KEY";
	// start up kii
	[Kii beginWithID:appID andKey:appKey];
	// start up kii analytics
	[KiiAnalytics beginWithID:appID andKey:appKey];
	// start up kii referral
	[KiiReferral beginWithID:appID andKey:appKey];
	// finish your initialization code
	return YES;

Connect with Facebook

In order to utilize the KiiReferral framework, you must connect your application to Facebook. This will allow users to post to their profile. If you have not already implemented Facebook's SDK connections, follow Facebook's instructions for connecting your app here.

Show the share view

This is the view that allows your users to post messages from within your app. Simply present the Kii Referral view controller and the library will take care of the rest:

Note: There must be a currently authenticated Kii User, otherwise the user will receive errors when they try to share! It's best to check this before presenting the view.

Simple use

If you wish to show your default message/configuration, you can simply use the following code:

KRShareViewController *vc = [KRShareViewController shareView];
[self presentViewController:vc animated:TRUE completion:nil];
Custom configuration key

If you wish to use a custom configuration key, simply specify that key using the following setup:

KRShareViewController *vc = [KRShareViewController shareViewWithConfigurationKey:@"my-configuration-key"];
[self presentViewController:vc animated:TRUE completion:nil];
Add custom metadata

If you wish to track other metrics about the share that is taking place, you can set an NSDictionary filled with parameters to associate with the share. Some examples of this might be: user level, location, device type, player type, points scored, etc. Those metrics can then be utilized (if you choose) later on in Kii's Analytics dashboard.

To add custom metadata, use the following technique:

NSDictionary *myDataDict = @{@"user_type": @"pro", @"player_score": [NSNumber numberWithInteger:293]};

KRShareViewController *vc = [KRShareViewController shareViewWithConfigurationKey:@"my-configuration-key"];
[vc setCustomInfo:myDataDict];
[self presentViewController:vc animated:TRUE completion:nil];

Get the user's referral statistics

You might choose to offer the user points or rewards based on how much they are sharing your app (and how many people actually convert!). You can use a simple SDK method to retrieve all of these results:

[KiiReferral getUserTotals:[KiiUser currentUser]
           completionBlock:^(KRStatisticObject *stats, NSError *error) {
           	if(error == nil) {
           		[stats describe];
           	} else {
           		NSLog(@"Error getting user totals: %@", error);

Open up the KRStatisticObject.h file (or command-click on the KRStatistic object declaration in the completion block) to view a list of properties accessible within this object.


If you're all done implementing and would like some extra features, check these out! If you have any ideas/suggestions on features you'd like to see, let us know in the comments!

Conversion Triggers

Let's say you want to reward a user for driving a conversion to your app (ex: get 40 points for each person that you get to download the app). To do this, we need to set up a trigger that executes some custom logic whenever a conversion event happens.

Fortunately, Kii offers Server Extensions that make this very easy! To make things even easier, we have included a directory in this project to get your server extension trigger set up very quickly.

Set up

To set up, you need to install the Kii CLI SDK and do some basic configuration. From there, we have provided a simple upload script to upload your server extension and hook seamlessly.

  1. cd into the triggers directory
  2. Install the Kii CLI SDK into this directory
    • For installation instructions, visit this page
    • If you have trouble installing, use sudo
      • Still having trouble installing?
        1. cd into the kii-cli directory (ex: cd kii-cli-vX.Y.Z)
        2. $ touch .npmignore
        3. $ npm install
  3. Modify upload.sh with your application credentials, site and the location of the kii-cli directory
  4. Execute $ sh upload.sh

Your server hook is now deployed!

Modifying your hook

The default script you just uploaded simply creates an app-scope object in the triggered_objects bucket when a conversion happens. To create your own logic, simply edit the referral-hook-source.js file and run $ sh upload.sh when you're done and ready to update the hook!


You get some default parameters when this javascript code is executed via the params parameter. The most useful will likely be the User ID of the original sharer (i.e. the user to be rewarded). That user id can be accessed by params.objectScope.userID

For more about server extensions, see the full guide here

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.