Kiip Web SDK

Overview

The Kiip Web SDK can integrate into a web or mobile web page. Read this guide for SDK features and integration instruction.

If you have any questions concerning this documentation, contact support@kiip.me.

Add kiip.js Script Tag

The Kiip Web SDK must be included as a script tag in your website like so:

<script type="text/javascript" src="//d3aq14vri881or.cloudfront.net/kiip.js"></script>

Creating a Kiip Instance

With the kiip.js script included in your website, you can instantiate the Kiip SDK. Perform the following command to instantiate Kiip:

var kiipInstance = new Kiip(app_key, callback, options);

A valid app_key for the Kiip Web SDK is provided on the “App Settings” page of the Kiip Dashboard.

callback is a function allowing control over when a reward shows. See below for more documentation on using callback.

options is a JSON object used set options for the Kiip Web SDK. options must be set before instantiating Kiip if being used.

Setting Options

Currently, only deviceId is available to set in the options parameter when instantiating the Kiip Web SDK. Here is an example:

// Set options before instatiating Kiip Instance
var options = {
	deviceId: "some_device_id"
}

// Pass options a the third parameter when instatiating Kiip
var kiipInstance = new Kiip(app_key, callback, options);

Limitations

There are a few limitations for a Kiip instance:

  • There cannot be more than one Kiip instance per page.
  • Calling new Kiip(app_key) more than once using the same app_key will return the same Kiip instance.
  • Attempting to instantiate Kiip with a new app_key will throw an error.

Once initialized, you can set a couple additional properties on your Kiip instance.

API Methods

.setTestMode()

kiipInstance.setTestMode();

Call this method to put the Kiip instance in test mode. This mode allows for testing the Kiip Web SDK during the integration process. Do not ship this to production.

Once set, test mode cannot be turned off unless the page is refreshed.

.setEmail()

kiipInstance.setEmail('email@example.com');

.setEmail() enables the pre-population of an email address for earned rewards. Call .setEmail() once for Kiip to pass the email address along to every reward a given user earns.

.setUserId() – enables virtual currency rewards

kiipInstance.setUserId('user-2203945');

Setting a user ID allows the Kiip Web SDK to attach virtual currency to a reward. An extra server-side verification is required to deliver a virtual currency reward. Documentation can be found below, under the section Virtual Currency Callback Documentation.

.setContainer() – optional

kiipInstance.setContainer('element-id');

.setContainer() is an optional API that specifies a container element for displaying a reward. Make sure to assign the container either an element-id string or an actual dom element.

By default, the reward will display as an overlay above your web page.

NOTE: It is highly recommended to NOT use the .setContainer() API for mobile web pages since the user may not see it.

NOTE 2: If a DOM element is given to .setContainer(), it must be inside the body element of your web page at all times. Due to security limitations within iframes, this must be done to prevent risk of reward loading issues.

Posting Moments

Once you have created your Kiip instance, post a moment at any time with this:

kiipInstance.postMoment('Moment Name');

A string (‘Moment Name’) describing the moment must be passed with this post. When .postMoment() is fired, it will send an async call to Kiip to determine whether the user receives a reward.

If the user does receive a reward, a couple things will happen.

If a callback is provided on instantiation, regardless of whether the user wins a reward, the callback will fire.

An example callback should look something like this:

// If unit exist, the user has won a reward, a unit will be
// provided as an argument. Unit is basically an object with
// two methods, “show” and “destroy”. You can call “show” when you are
// ready. If unit is undefined or false, then the user did not
// earn a reward.
var callback = function(unit){
    if (unit) {
        // User earned a reward, show it
        unit.show();
    } else {
        // User did not earn a reward... do something else
    }
};
new Kiip(app_key, callback);

If no callback was provided on instantiation and the user earns a reward, the reward shows immediately. Using no callback is recommended as the simplest route for posting moments to the Kiip Web SDK.

NOTE: unit only has two available commands, .show() and .destroy(). .destroy() should only be used in emergencies as calling it could interrupt user redemption. The unit will destroy itself automatically after a reward has been redeemed.

unit.show()

An optional callback can be provided when calling unit.show(). This method will fire when the unit is either closed after reward redemption or upon cancellation. This method will also be fired when using unit.destroy().

var callback = function(unit){
    if (unit) {
        // The function must be passed in as the first argument like seen below:
        unit.show(function(){
            console.log('This function will be fired the unit has been closed');
        });
    } else {
        // User did not earn a reward... do something else
    }
};
new Kiip(app_key, callback);

Unloading Kiip Instance

It will likely never be needed to unload the Kiip instance. If you have a highly interactive page and want to unload or stop the Kiip instance, do so at any time by calling kiip.unload().

Example Implementation

This is the simplest implementation of the Kiip Web SDK:

// We first create our kiip instance
var kiipInstance = new Kiip(app_key, callback);

// Some time goes by, user clicks on a special button:
kiipInstance.postMoment('Amazing Task Accomplished!');

// More time goes by... user signs up for a newsletter
kiipInstance.postMoment('Another Amazing Task Accomplished!');

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.

When a user redeems a reward, the Kiip servers will immediately POST a request to the callback URL specified in your setup.

The POST request will contain the following data:

  • 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 redemption callback using this string containing the following:

sha1(transaction_id + app_secret)

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

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

Virtual Currency Callback

This serverside callback will verify virtual currency for delivery when users earn Kiip rewards.

1. Include the User Id in the Kiip WebSDK

Make sure to set up the Kiip Web SDK and include a User ID. The User ID will be sent via the callback to specify which account to apply virtual currency.

// We first create our Kiip instance
var kiipInstance = new Kiip(app_key, callback);
// We must set a User Id
kiipInstance.setUserId('user-2203945');

2. Specify Callback URL for Virtual Currency

When a user redeems a reward containing virtual currency, the Kiip servers will immediately POST a request to the callback URL specified in your setup.

This requires creating an endpoint on an accessible server.

The POST request will contain the following data:

content (string): The unique identifier of the virtual currency (e.g. coins)
quantity (int): The quantity of the virtual currency (e.g. 20)
user_id (string): The User ID specified to the Kiip Web SDK. Virtual currency will be applied to this User ID.
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.

3. Verify the Callback

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