Welcome to the Kwegg API Docs

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

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:

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:

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.

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

Request field

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

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

Request Fields

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:

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

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

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
    }
}