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.

.setUserData() – optional

kiipInstance.setUserData({
	'birthday': '06/25/1983',
	'gender': 'm',
	'age': '34'
});

.setUserData() is an optional API that allows you to add more user data in the format of a JSON object. We currently support these properties in the JSON object:

  • birthday - Possible date formats are MM/DD/YYYY and YYYY-MM-DD
  • gender - Possible values are any case-insensitve string that starts with ‘f’ or ‘m’ for female and male respectively.
  • age - Any integer value

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 earned a reward and a unit will be
// provided as an argument. Unit is essentially 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.

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

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

Rewarded Video

Access more inventory, increase engagement and drive more revenue with Rewarded Video. To utilize Rewarded Video, designate and individual moments placement in the Kiip dashboard.

Kiip Rewarded Video Moment

Native Rewards (In-Feed)

Native Rewards offer more control over how Kiip rewards display. In most cases, Native Rewards are used to control display positioning. Containers designated for a Native Rewards must be 300px by 250px.

Use the .setContainer() method described below for Native Reward placements.

Make sure to use the Kiip dashboard to designate moments in which Native rewards should display: Native Moment

.setContainer()

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.

Custom Notifications

The Kiip WebSDK offers more flexibility for custom notifications. To create a custom notification that displays before a reward is shown, make sure you’ve declared a callback when instantiating Kiip.

Then, use the callback to create a UI element or button that when clicked, calls unit.show().

var callback = function(unit){
    if (unit) {
        // User earned a reward, create/show notification
	// that will handle the .show() event.
    } else {
        // User did not earn a reward... do something else
    }
};
new Kiip(app_key, callback);