Mobile Rewards

Base URL for requests

http://verizonventures-prod.apigee.net/kiip

Kiip connects brands with people in rewarding ways. It allows Brands to reach their audience at the right moments. They can engage people in various ways:

  • Fitness Moments - Celebrate their completed workouts.
  • Musical Moments - Amplify listeners’ new favorite tracks.
  • Gaming Moments - Cheer on gamers’ new high scores.
  • Shopping Moments - Appreciate shoppers for completed errands.
  • Productivity Moments - Recognize their cleared to-do lists.
  • Cooking Moments - Be there when household cooks discover new recipes.

 

Kiip allows developers to engage users with rewards from the brands they love. Developers add value by rewarding users during the most engaging moments. Kiip features that appeal to most developers include:

 

  • Flexible and Simple Integration - Kiip supports iOS and Android with additional tools for Unity, Phonegap, Adobe Native Extension and Marmalade.
  • Diverse Reward Inventory - We provide a mix of brand reward inventory that is relevant and targeted for your users.
  • Beautiful User Experience - Users welcome rewards with 10x average mobile engagement rates. Kiip also makes it easy to customize the reward experience to fit your app.
  • Data and Analytics - Real-time access to the data that matters to your apps. Kiip analytics are actionable so you can make better decisions.
  • User Retention - Get users back in your app. Users who engage with Kiip come back 30% more often.
  • Locatization - Kiip rewards are global and localized for 18 different languages.

 

Integration Details

Developers that do not want to use the Kiip mobile or web SDK may use REST APIs for integration with the Kiip platform.

The following flow is used when integrating with REST APIs:

  1. Initiate a user session when a device comes online by calling the Session endpoint.
  2. For every action your application deems rewardable, make a server call using the Moment endpoint. The Kiip Platform will return a reward if we are able to reward the moment. When testing, passing the test flag as true will ensure a reward is always returned.

Session Endpoint

Start a session when you want Kiip to track a new user you wish to reward. The below describes the format of the call needed to start a session.

POST /kiip/2.0/web/moment/ HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: verizonventures-prod.apigee.net

{
    "app_key": <app key>,
    "device_id": <device id>,
    "events":[
        {
             "id": "session_start",
             "start": <session start time in ISO8601 format>
        }
    ],
    "protocol": "http",
    "sdk_version": "1.0",
    "test": <is test moment: true | false>
}

JSON Payload Components:

  • app_key: kiip application key found in the dashboard.
  • device_id: the device specifc advertiser identifier (if user has opted out see below).
  • events: list of user specific events, to start a server to server session a single element with id of ‘session_start’ and start as current ISO8601 formated time is required.
  • protocol: wire protocol, we currently only support ‘http’
  • sdk_version: version of the sdk that you are using, we currently only support ‘1.0’.
  • test: whether this is a test request, test requests will always be filled

Notes:

  • A parameter r (time in seconds since epoch) can be added to the URL to prevent web browser caching
POST /kiip/2.0/web/moment/?r=<time in seconds since epoch> HTTP/1.1

Example Request

http://verizonventures-prod.apigee.net/kiip/2.0/web/moment/?r=<time in seconds since epoch>&vzvkey=<Your Verizon Ventures key>

Payload
{
    "app_key": <app key>,
    "device_id": <device id>,
    "events":[
        {
             "id": "session_start",
             "start": <session start time in ISO8601 format>
        }
    ],
    "protocol": "http",
    "sdk_version": "1.0",
    "test": <is test moment: true | false>
}

e.g.

http://verizonventures-prod.apigee.net/kiip/2.0/web/moment/?r=1422408743271&vzvkey=8N2jILcGb9qpU2soWsy16KMOABfvjbIQ

Payload
{
    "app_key": "2a67fadc7dd600d73f586dabe3ccc470",
    "device_id": "acme-4ce34c50-bf87-4b00-6eb1-0ab0d6147788",
    "events":[
        {
             "id": "session_start",
             "start": "2015-01-28T01:32:22.852Z"
        }
    ],
    "protocol": "http",
    "sdk_version": "1.0",
    "test": true
}

Response

The server will respond to valid requests with a JSON document containing a single key date holding the session start time in ISO8601 format.

{
     "date": "2015-01-28T01:32:22.852Z"
}

Moment Endpoint

When a user completes a rewardable event, the server should make a call to the moment endpoint requesting a reward. The call is described below. If Kiip deems the moment rewardable, a JSON document will be returned containing the reward information. Otherwise, no reward will be returned.

POST /kiip/2.0/web/moment/ HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: verizonventures-prod.apigee.net

{
     "app_key": <app key>,
     "device_id": <device id>,
     "moment_id": <user data about moment>,
     "protocol": "http",
     "sdk_version": "1.0",
     "test": <is test moment: true | false>
}

JSON Payload Components:

  • app_key: kiip application key found in the dashboard.
  • device_id: the device specifc advertiser identifier (if user has opted out see below).
  • moment_id: user specific string representing the moment.
  • protocol: wire protocol, we currently only support ‘http’
  • sdk_version: version of the sdk that you are using, we currently only support ‘1.0’.
  • test: whether this is a test request, test requests will always be filled

Notes:

  • An parameter r (time in seconds since epoch) can be added to the URL to prevent web browser caching
POST /kiip/2.0/web/moment/?r=<time in seconds since epoch>&vzvkey=<Your Verizon Ventures key> HTTP/1.1

Example Request

http://verizonventures-prod.apigee.net/kiip/2.0/web/moment/?r=<time in seconds since epoch>&vzvkey=<Your Verizon Ventures key>

Payload
{
     "app_key": <app key>,
     "device_id": <device id>,
     "moment_id": <user data about moment>,
     "protocol": "http",
     "sdk_version": "1.0",
     "test": <is test moment>
}

e.g.

http://verizonventures-prod.apigee.net/kiip/2.0/web/moment/?r=1422386594153&vzvkey=8N2jILcGb9qpU2soWsy16KMOABfvjbIQ

Payload
{
    "app_key": "2a67fadc7dd600d73f586dabe3ccc470",
    "device_id": "acme-4ce34c50-bf87-4b00-6eb1-0ab0d6147788",
    "moment_id": "reading the article",
    "protocol": "http",
    "sdk_version": "1.0",
    "test": true
}

Response

{
    "date": <current date>,
    "view": {
        "id": <view id>,
        "modal": {
            "message": <message>,
            "body_url": <url>,
            "title": <title>
        }
    }
}

e.g.

{
    "date": "2015-01-27T23:57:42.864735",
    "view": {
        "id": "test_509821a1-48cf-59b6-38cd-d7cb63e20cbb",
        "modal": {
            "message": "Test Reward - Real Reward",
            "body_url": "http://api.kiip.me/reward/preview/509821a1-48cf-59b6-38cd-d7cb63e20cbb?locale=&sdk_version=2.0.9&r=394542&application_id=545ab108-1cc7-86ca-0031-2b8b91b9141f&moment_id=5463e141-93ad-6f92-42e3-25a55294b9ac",
            "title": "Loading your Kiip Reward:"
        }
    }
}

Display Reward

If a moment is deemed rewardable, the above Moment call will return a JSON document describing the reward. The document contains a key view.modal.body_url that is the URL to the HTML page displaying the reward. This URL is typically rendered in an iframe or webview. Appending #show to the URL will display the reward unit.

GET <view.modal.body_url> HTTP/1.1

Example Request

http://api.kiip.me/reward/preview/<reward id>?locale=<locale>&sdk_version=<sdk version>&r=394542&application_id=<application id>&moment_id=<moment id>

e.g.

http://api.kiip.me/reward/preview/509821a1-48cf-59b6-38cd-d7cb63e20cbb?locale=&sdk_version=2.0.9&r=394542&application_id=545ab108-1cc7-86ca-0031-2b8b91b9141f&moment_id=5463e141-93ad-6f92-42e3-25a55294b9ac

Displays the reward unit.

http://api.kiip.me/reward/preview/509821a1-48cf-59b6-38cd-d7cb63e20cbb?locale=&sdk_version=2.0.9&r=394542&application_id=545ab108-1cc7-86ca-0031-2b8b91b9141f&moment_id=5463e141-93ad-6f92-42e3-25a55294b9ac#show

Notes about Device IDs

All calls to the Kiip platform must include a valid device ID. In most cases, the device ID should be the device specific Advertiser Identifier that is returned by the mobile operating system.

When a user has opted out of advertiser tracking, the Advertiser Identifier will be empty. In this case, the caller must generate a device ID specific to that device. A user generated device ID should be a hexidecimal string separated by dashes (-) in the pattern show below and prefixed with your assigned company token. Standard UUID generators can usually be used to generate the hexidecimal string.

<company token>-00000000-0000-0000-0000-000000000000

e.g.

acme-4ce34c50-bf87-4b00-6eb1-0ab0d6147788