Kiip Web SDK
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 firstname.lastname@example.org.
Note: Due to GDPR regulations, Kiip is now blocking all ad requests from the affected EEA regions.
Add kiip.js Script Tag
The Kiip Web SDK must be included as a script tag in your website like so:
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:
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.
longitude is available to set in the options parameter when instantiating the Kiip Web SDK. Here is an example:
There are a few limitations for a Kiip instance:
- There cannot be more than one Kiip instance per page.
new Kiip(app_key)more than once using the same
app_keywill return the same Kiip instance.
- Attempting to instantiate Kiip with a new
app_keywill throw an error.
Once initialized, you can set a couple additional properties on your Kiip instance.
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.
When testing from outside the US it is recommended to use a US-based VPN connection when requesting rewards. Test rewards fill 100% of the time, whereas with live/production rewards it is expected that not every request will be filled with a reward. It is important that you add the correct device identifier inside the Test Devices section of the Kiip App Dashboard.
.setEmail() enables the pre-population of an email address for earned rewards.
.setEmail() once for Kiip to pass the email address along to every reward a
given user earns.
.setUserId() – enables virtual currency rewards
Setting a user ID allows the Kiip Web SDK to attach virtual currency to a reward. Including it increases the potential revenue you can earn, as some rewards require it for delivery.
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
.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
Once you have created your Kiip instance, post a moment at any time with this:
A string (‘Moment Name’) describing the moment must be passed with this post.
.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 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.
unit only has two available commands,
.destroy() should only be used in emergencies as calling it could interrupt
user redemption. The
unit will destroy itself automatically after a reward has
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
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
This is the simplest implementation of the Kiip Web SDK:
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.
Required: Callback URLs must be served over
Virtual Currency Callback
This server-side 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.
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.
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 HMAC 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:
Here’s a quick example of how you would verify the request in python:
Virtual Currency Reward Issuance Endpoint (optional)
The issuance endpoint will receive commands from Kiip to issue virtual currency in response to later events, such as an application install, survey completion, or purchase. This does require a user_id be set on the Kiip object.
As the message format is different from virtual currency reward redemption verification messages, it is possible to reuse the endpoint for this purpose.
The JSON 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): 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 linked reward ID.
- nonce (string): A string, when combined with the transaction ID, can be used to uniquely reference a message.
- origin (string): The event that triggered this issuance event (i.e., survey, other).
- signature (string): The HMAC of the payload. Used to verify valid POSTs. See below for more information.
Verify a virtual currency issuance command using this string containing the following:
Here’s a quick example of how you would verify the request in python:
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.
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.
.setContainer() method described below for Native Reward placements.
Make sure to use the Kiip dashboard to designate moments in which Native rewards should display:
.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.
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
The Kiip WebSDK also offers the abilty to add event listeners by calling
addEventListener(eventName) on the WebSDK instance. You can currently listen to these event names:
NOTE: Other than listening to the unitRedeemSuccess event to know if the reward was redeemed successfully, you can also use a callback in unit.show(isRedeemed) when posting moments. Please the documention above on Unit Show for an example.