Toggle navigation

Welcome to the Kwegg API Docs

Version 1.0.0

Click here to navigate to the home page

Here you’ll find the guides, resources, and references to stimulate your application with Kwegg APIs. In the back of these APIs is an operational loyalty and rewards engine held up by the blockchain mechanism.

Kwegg’s REST APIs assist your application in listening and keeping a record of all micro user-interactions to enable incentivization for the users. Kwegg’s redemptions dashboard allows you to add partner brands and configure distinct rules to reward and motivate users. It intends to build an advanced economic model for your business application.

Each client will be allowed to pre-define the list of events or user actions suitable to their platform and their users. When performing the actions, the user will be rewarded with a certain number of reward coins. With each user action, a number associated will define the number of coins rewarded to the user for acting on the client platform.

Example:

The following can be user actions for a Food Delivery Application.

  • Sign up
  • Order food
  • Write a review for a restaurant.
  • Rate the rider
  • Visiting the homepage of the application daily

Frequency Cap

The frequency cap determines the recurrence of an event for a time period. There is an option to configure the frequency cap for each event, in the form of ‘once per n minutes/hours/days. This means the user will only receive coins once per n minutes/hours/days, irrespective of repetitive user actions. Else it can be an ‘open’ category, which listens to any user micro-action and credits the corresponding number of coins in the user wallet. This feature is helpful for events like Daily check-in, etc.

Parameters

Each event can have multiple parameters. Each parameter will have a name, a data type{Integer, String, Boolean, Float}, and a mandatory/optional flag where-in an event, when logged, can be ignored if a few mandatory parameters are incomplete. It is treated as some meta information along with the occurrence of a user action.

Example – For an event called WATCHED_VIDEO, the parameter can be the duration.

Rules

Each event (or user action) can have multiple rules. A rule is an ‘if-then’ statement that applies to one or more parameters of the event. It decides the number of coins/points be rewarded as per the conditions/constraints applied.

Each condition can have one or more than one logical ‘ANDed’ statements. A condition contains three components:

  1. Meta parameter
  2. Logical operation – This depends upon the data type.
  3. Value/Values

 

Condition component mapping

Data type

Logical operation

Integer, Float Equal to
Less than
Greater than
Is Empty
Is not empty
String Equal to
Contains
Starts with
Ends with
Is empty
Is not empty
Boolean Equal to
Is Empty
Is not empty

 

There will be a mandatory rule called the ‘default rule,’ which will be implied if no other rule matches. The default rule will have no condition, just the points value.

Example – Single statement conditions

If for the event called WATCHED_VIDEO, Here’s the use-case:

If the video is watched for 10 minutes, give 100 points. If the video is watched for 20 minutes, give 200 points. For more than 20 minutes of watch time, give 500 coins. In all the other cases, give 50 coins.”

In the above case, the event will be configured with the following four rules:

 

Condition

Reward points

Priority

Duration equals to 10 100 1
Duration equals to 20 200 2
Duration greater than 20 500 3
DEFAULT RULE 50 POSITIVE_INFINITY

 

Example – Multiple statement condition

If for the event called WATCHED_VIDEO, Here’s the use-case:

“If the type of the video is `PRANK,` give 100 points. If the video type is `RECIPE` and the video is watched up to 10 minutes, give 200 points; otherwise, give 500 points. In all the other cases, give 50 points.”

In the above case, the event will be configured with the following three rules:

 

Condition

Reward points

Priority

Type equals to PRANK 100 1
Type equals to RECIPE AND Duration less than 10 200 2
Type equals to RECIPE 500 3
DEFAULT RULE 50 4

 

Streak

A streak is a recurrence of multiple occurrences of a user action over a period of time to let the user earn the reward. At the end of the streak, the user gets the rewards. Each event will have an option to configure a streak against itself to define the rewards as per the use case. Streaks can of two types:

  1. x events per day for consecutively y days
  2. x events before a particular timestamp

Types of Rewards

Based on the complexity of the rewarding rules, the rewards can be of the following types:

Basic reward

This is a pretty simple rewarding technique, where a user gets some reward coins on each occurrence of an event (or user action) without any restrictions on time, frequency, metadata. Here, the user gets rewarded every time that action is performed, irrespective of the associated meta. Example – Review a commercial product item and get 10 points.

 

Frequency capped reward

This type of reward includes a Frequency Cap associated with the rewarding rule, and the user gets coins only once per x minutes/hours/day.

 

Meta based reward

This includes some rules to be applied on the meta Parameters, which give conditional rewards based on the parameters’ values. Each user action can have multiple Rules. Each rule with a priority to be compared first and, if matched, get applied and provide rewards accordingly.

Example – Watch the video for 10 minutes and get 100 points; watch the video for 20 minutes and get 200 coins.

 

Streak based reward

This type of reward is suitable when there is a recurrence of a user action multiple times and eventually results in the user getting rewarded, once at the end of the streak. This is configured in the following two forms:

     x occurrences per day for y consecutive days

Example – Open app twice every day for 10 days and get 100 points

     x occurrences before a particular timestamp

Example – Do 4 mobile recharges before 30th September 2020 and get 200 points.

 

Hybrid reward

Any combination of the above two non-basic rewards results in the formation of a hybrid reward. Example – Watch a movie for 10 minutes daily for 10 days regularly and get 200 points. This example consists of a Meta based reward and a Streak-based reward.

 

Programmatic reward

This is a separate kind of custom reward wherein an event’s occurrence should call a RESTFul API to some other microservice or the tenant system to get the number of points to be rewarded for that occurrence. The platform takes in input the following API data from the tenant for a particular event:

  1. URL
  2. HTTP method
  3. Headers list
  4. Body parameters

The data that is to be returned from the API will be fixed, and any external system will have to follow the JSON structure to return the number of rewards.

 

Kwegg system allows tenants to integrate via REST APIs to track their user actions on Kwegg servers. A tenant can log in to their users on the Kwegg backend and receive a back access token that can be used in subsequent APIs. Kwegg allows tenants to fetch coin balances of their users and register/trigger user actions that are rewardable as per their customization on the Kwegg admin dashboard.

Introduction

Let’s test out running Kwegg locally by cloning the Quickstart app. You’ll need API keys, which you can receive by signing up in the Dashboard.

API Reference

An extensive reference to integrate with Kwegg API endpoints

 

BaseURL

https://dev-api.kwegg.com/

Tenent User Login

Kwegg maintains your users at our servers to keep track of your user’s balance and activities that the user performs in your app. Each of your users is uniquely identified on our system by the identifier(userId) that you provide to us. This API is used to Login/Signup a tenant user on the Kwegg system and returns an access token to authenticate subsequent requests.

 

POST -  {{BaseURL}}/userauth/user/tenant/login

 

Header

Parameter

Datatype

Description

License-Key String The license key is communicated to the customer via email.
Platform String The platform is the client-side platform that is hitting the APIs – (ANDROID, WEB, IOS)

 

Request field

Parameter

Datatype

Description

Mandatory

Example

userId  String Your UserId to verify the user credentials Yes “12”

Request Body Example

{
    "userId":"12"
}

 

cURL

curl --location --request POST '{{BaseURL}}/userauth/user/tenant/login' \
--header 'License-Key: TESTONE1234' \
--header 'Platform: RAW' \
--header 'Content-Type: application/json' \
--data-raw '{
    "userId":"12"
}'

Response Body Example

{
    "success": true,
    "message": "Login successfully",
    "data": {
        "accessToken": "afn770-484f0af24b2b91cc9c61a9206d0681e6",
        "user": {
            "userId": "12",
            "balance": 0
        }
    }
}

 

Here accessToken is the token required to access other API endpoints of the system.

Tenant User Fetch Balance

Kwegg server stores the balance of each of the tenant users. This API aims to fetch the balance of the user associated with a particular userId.

GET -  {{BaseURL}}/userauth/user/tenant/balance?userId=12&=

 

Header

Parameter

Datatype

Description

License-Key String The license key is communicated to the customer via email.
Platform String The platform is the client-side platform that is hitting the APIs – (ANDROID, WEB, IOS)
Authorization String The accessToken will be used here to give authorization to the user to fetch balance.

 

cURL

curl --location --request GET '{{BaseURL}}/user/tenant/balance?userId=12&=' \
--header 'License-Key: TESTONE1234' \
--header 'Platform: RAW' \
--header 'Authorization: <accessToken>' \
--data-raw ''

 

 

Response Body Example

{
    "success": true,
    "message": "Balance fetched successfully",
    "data": {
        "balance": 0
    }
}

 

Register Tenant user event occurrence

For each of the events defined in the dashboard for the user’s activity in the tenant’s app, the tenant system can trigger an event occurrence with the Kwegg server. This API is used to register/trigger an event occurrence from the tenant’s side to Kwegg’s system and required the access token that is received from the tenant user login API.

POST - {{BaseURL}}/core/user/tenant/event/occurence?=

 

Header

Parameter

Datatype

Description

License-Key String The license key will be communicated to the customer via email.
Platform String The platform is the client-side platform that is hitting the APIs – (ANDROID, WEB, IOS)
Authorization String The accessToken is used here to give authorization to the user to fetch balance.

 

Request Fields

Parameters

Datatypes

Description

Mandatory

Example

userId String Your UserId to verify the user credentials. yes “12”
event Object Event attributes by the user as key-value pairs.  yes {“name”:“product_viewed”,“id”:“23”}
name String Name of the event performed by the user. yes “product_viewed”
params Object An array of attributes of the event occurred. yes {“id”:“1234”, “name”: “event1” }
id string Specifies the event id of the event performed by the user. yes “1234”

 

Request Body Example

{
    "userId":"12",
    "event":{
        "name":"product_viewed",
        "params":{
            "id":"1234"
        }
    }
}

cURL

curl --location --request POST '{{BaseURL}}/core/user/tenant/event/occurence?=' \
--header 'License-Key: TESTONE1234' \
--header 'Platform: RAW' \
--header 'Authorization: <acessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "userId":"12",
    "event":{
        "name":"product_viewed",
        "params":{
            "id":"1234"
        }
    }
}'

 

Response Body Example

{
    "success": true,
    "message": "Event triggered successfully",
    "data": null
}

 

Tenant user Fetch Transactions

This API aims to fetch and display the transaction details (credit or debit points) of the user who encountered any event based on the application.

 

GET -{{BaseURL}}/core/user/tenant/transactions?page=1&numOfItems=5

 

Header:

Parameter

Datatype

Description

License-Key String The license key is communicated to the customer via email.
Platform String The platform is the client-side platform that is hitting the APIs – (ANDROID, WEB, IOS)
Authorization String The accessToken will be used here to give authorization to the user to fetch balance.

 

cURL

curl --location --request GET 'https://dev-api.kwegg.com/core/user/tenant/transactions?page=1&numOfItems=5' \
--header 'License-Key: TESTONE1234' \
--header 'Platform: RAW' \
--header 'Authorization: <accessToken>' \
--data-raw ''

 

Response Body Example

{
    "success": true,
    "message": "Transactions fetched successfully",
    "data": {
        "transactions": [
            {
                "id": "224b96ae-5c22-4e22-b484-7a15cccaa92d",
                "entry": "CREDIT",
                "createdAt": "2021-02-03T16:43:06.482441Z",
                "type": "EVENT_OCCURENCE",
                "points": 2
            }
        ],
        "totalCount": 5
    }
}

 

Fetch Offers

This API aims to fetch and display offers to the customers with all the associated customer details and the current status of the offer.

GET - {{eggsBaseUrl}}/userauth/admins/tenant?page=1&numOfItems=2

 

Header

Parameter

Datatype

Description

License-Key String The license key is communicated to the customer via email.
Platform String The platform is the client-side platform that is hitting the APIs – (ANDROID, WEB, IOS)

 

cURL

curl --location --request GET 'https://dev-api.kwegg.com/userauth/admins/tenant?page=1&numOfItems=2' \
--header 'License-Key: TESTONE1234' \
--header 'Platform: RAW' \
--header 'Authorization: <accessToken>'

Response Body Example

"success": true,
    "message": "Admins fetched successfully",
    "data": {
        "admins": [
            {
                "id": "82204c64-864d-48a2-ab71-00501db18ccf",
                "createdAt": "2020-10-21T19:30:22.495968Z",
                "email": "jack@gmail.com",
                "firstName": "Jack",
                "lastName": "One",
                "role": "VIEWER",
                "status": "PENDING"
            },
            {
                "id": "e534d8b3-6403-4fa8-89d0-261383dac3f8",
                "createdAt": "2020-11-03T20:24:34.030307Z",
                "email": "jack@gmail.com",
                "firstName": "Jack",
                "lastName": "Two",
                "role": "VIEWER",
                "status": "ACTIVE"
            }
        ],
        "totalCount": 4
    }
}

 

Redeem an offer

This API aims to fetch and display offers to the customers with all the associated customer details and the current status of the offer.

GET - {{eggsBaseUrl}}/userauth/admins/tenant?page=1&numOfItems=2

 

Header

Parameter

Datatype

Description

License-Key String The license key is communicated to the customer via email.
Platform String The platform is the client-side platform that is hitting the APIs – (ANDROID, WEB, IOS)

 

cURL

curl --location --request GET 'https://dev-api.kwegg.com/userauth/admins/tenant?page=1&numOfItems=2' \
--header 'License-Key: TESTONE1234' \
--header 'Platform: RAW' \
--header 'Authorization: <accessToken>'

 

Response Body Example

"success": true,
    "message": "Admins fetched successfully",
    "data": {
        "admins": [
            {
                "id": "82204c64-864d-48a2-ab71-00501db18ccf",
                "createdAt": "2020-10-21T19:30:22.495968Z",
                "email": "jack@gmail.com",
                "firstName": "Jack",
                "lastName": "One",
                "role": "VIEWER",
                "status": "PENDING"
            },
            {
                "id": "e534d8b3-6403-4fa8-89d0-261383dac3f8",
                "createdAt": "2020-11-03T20:24:34.030307Z",
                "email": "jack@gmail.com",
                "firstName": "Jack",
                "lastName": "Two",
                "role": "VIEWER",
                "status": "ACTIVE"
            }
        ],
        "totalCount": 4
    }
}