Object Reference
This section provides a list of the objects dealt with using the available API endpoints.
The cashback object is returned in the Configurations API response body. It describes the cashback program configurations.
Parameter | Type | Description |
rewardFactor | number | In case you have different merchants (brands) on your platform, The rewardFactor defines the specific cashback percentage for the paid amount to be rewarded to your players.Example: If you give 5% cashback (when the customer pays 100 USD, they will get 5 USD cashback). The rewardFactor would be 0.05 |
amountRewardThreshold | integer | Defines the amount of unit currencies needed to reward the player as per cashback rules.
Example: For every 10 USD spent the player gets rewarded by 5 points, implies that the amountRewardThreshold is "10". |
rewardWalletFactor | integer | Determines the points rewarded for each unit currency your player spends. Example: 2 points for every 1 USD spent, implies that the rewardWalletFactor is "2" |
rewardRankFactor | integer | In case your level up method is score, this factor determines the score rewarded for each unit currency your player spends. Example: 2 Score for every 1 USD spent, implies that the rewardRankFactor is "2" |
{
"rewardFactor":0.3,
"amountRewardThreshold":10,
"rewardWalletFactor":3,
"rewardRankFactor":1
}
Represents the challenge object that describes a configured challenge and tracks the relative player's progress.
Parameter | Type | Description |
id | integer | Unique identifier for the challenge. |
name | string | Challenge Name |
description | string | Challenge Description |
rankReward | integer | Awarded rank upon challenge completion |
walletReward | integer | Awarded points upon challenge completion |
repeatable | boolean | A flag that indicates whether the challenge is repeatable or not. |
maxAchievement | integer | An integer that defines how many times a player can achieve that challenge. |
type | string | The type of the challenge. Possible values are as follows:
SignUp SocialMedia ScheduledChallenge EventBased HighScore Birthday Anniversary |
visibility | string | Defines the visibility of the challenge. Possible values are:
|
icon | string | The icon's URL of the challenge. |
availability | object | "availability":{ "minLevel": 4, "tags": ["VIP"] } An object that describes challenge availability to players.
|
{
"id":3350,
"name":"view product + tag internal",
"description":"",
"rankReward":3,
"walletReward":10,
"repeatable":true,
"maxAchievement":0,
"type":"EventBased",
"visibility":"AlwaysVisible",
"icon":"[email protected]",
"availability":{
"minLevel":5,
"tags":[
"2nd tag"
]
}
}
The Event object is how you record any actions your users perform, along with any metadata that describe the action. For further elaboration on events check Understand your players' events.
Event Name | Key | Value |
buy | product_id | a123456 |
| price | 30 |
| product_category | fashion |
| product_tags | men & new_collection |
"buy": {
"product_id": "a123456",
"price": 30,
"product_category": "fashion"
"product_tags": ["men", "new_collection"]
}
The following example shows a collection of events
"events": {
"buy": {
"category": "Electronics",
"amount": 300
},
"travel": {
"destinations": ["Paris", "Cairo"],
"tickets": 4,
"season": "Winter"
},
"visit_branch": {}
}
Defines the player rank and progress in the leaderboard based on the specified query parameters.
Parameter | Type | Description |
displayName | string | Player's display name. |
playerUniqueId | string | Unique identifier for a player at Gameball. |
progress | integer | Player's progress (based on the specified query parameters). |
rank | integer | Player's Rank (based on the specified query parameters). |
levelName | string | Level Name. Example: "Bronze" |
levelIcon | string | Level's icon URL. |
{
"displayName": "Player 1",
"playerUniqueId": "5097238429738",
"progress": 1748,
"rank":1,
"levelName": "Bronze",
"levelIcon": "https://cdn.gameball.co/uploads/c007/[email protected]"
}
Contains information about the player's current level.
Parameter | Type | Description |
minProgress | integer | The required score to reach the level. |
order | integer | Level Order |
icon | string | icon URL of the level. |
name | string | Level Name |
benefits | object | "benefits":{ "rankReward":0, "walletReward":0, "levelDiscount":0, "discountCapping":0, "others":[] } The benefits object is defined as follows:
|
{
"name": "Gold",
"description": null,
"levelStartScore": 7500,
"levelOrder": 4,
"iconPath": "https://cdn.gameball.co/uploads/Client 1/[email protected]",
"benefits": {
"scoreEnteryReward": 0,
"pointsEnteryReward": 0,
"levelDiscount": null,
"discountCapping": null
}
}
Represent a Product in your system with its relative information, this object is used in the Orders API.
Attribute | Type | Description |
productId | string | The ID of the product that the line item belongs to |
sku | string | The item's SKU (stock keeping unit). |
title | string | The title of the product. |
category | array | Product category (fashion, electronics.. etc). It can be one category or multiple categories. Example: ["natural","cosmetics"] |
collection | array | Collection ID(s) to which the product belongs. It can be one collection or multiple collections. This will be also based on the available collections in your store. Example: ["14313","4343"] |
tags | array | Tag(s) attached to the item in the order. Example: ["VIP", "Elite"] |
weight | number | Item weight. Must be positive. |
vendor | string | The name of the item's supplier. Example: "nike" |
{
"productId":"197765",
"tag": ["VIP"],
"category": [
"natural",
"cosmetics"
],
"weight": "20",
"vendor": "nike",
"collection": ["14313", "4343"]
}
Holds information of merchant and its branch
Parameter | Type | Description |
uniqueId | string | Merchant unique id or code |
name | string | Merchant name |
branch | string | Optional branch information |
branch.uniqueId | string | Branch unique id or code |
branch.name | string | Branch name |
"merchant": {
"uniqueId": "string",
"name": "string",
"branch": {
"uniqueId": "string",
"name": "string"
}
}
Represents a notification that your player receives.
Attribute | Type | Description |
notificationId | string | Unique Identifier for a notification |
title | string | Notification Title |
body | string | Notification Body |
isRead | boolean | Indicates whether the notification is read or not. |
createdAt | string | Notification's creation date, as an ISO8601 timestamp. Example: "2019-09-21T16:53:28.190Z" |
lang | string | The language in which the notification is displayed. In case the lang is not provided in the request, defaultlang is returned.Note: The language provided should be as per configured languages in your account. Example: "en" , "fr" . |
icon | string | Notification's icon URL. |
{
"notificationId" : "123",
"title": "New level!",
"body": "Keep it up! You are now on Bronze ",
"isRead": true,
"createdAt": "2021-05-12T00:08:09.646174",
"lang": "en",
"icon": "https://cdn.gameball.co/uploads/client776/ad8b2587-959f-48fd-ab58-a643323652begb-icon-level-13.png"
}
Contains info about the player's score.
Parameter | Type | Description |
scoreBalance | string | Player Score |
scoreName | string | The naming of the score points that appears to the player. |
"score": {
"scoreBalance": 15830,
"scoreName": "Score"
}
Contains all of the attributes describing your player.
Parameter | Type | Description |
displayName | string | Player's display name |
firstName | string | Player's first name |
lastName | string | Player's last name |
gender | string | Player's gender. Example: M or F, Male or Female. |
email | string | Player's email |
mobile | string | Player's mobile |
dateOfBirth | string | Player's date of birth Example: "1980-09-19T00:00:00.000Z" |
joinDate | string | Player join date at your system. Example: "2019-09-19T21:06:29.158Z" |
tags | string | Comma separated string of tags to be attached to the player. Example: "VIP,Platinum" |
community | string | Describe which community a player belongs to. |
custom | object | Key value pairs of any extra player attributes. {"class" : "E2022", "weight" : 78} |
"playerAttributes": {
"displayName":"Jon Snow",
"firstName": "Jon",
"lastName": "Snow",
"email":"[email protected]",
"mobile": "+1234567",
"gender":"M",
"dateOfBirth":"1980-09-19T00:00:00.000Z",
"joinDate":"2019-09-19T21:06:29.158Z",
"tags": "VIP,Platinum",
"custom":{
"location":"Miami",
"graduationDate":"2018-07-04T21:06:29.158Z",
"isMarried":false
}
}
Contains information about the player's points.
Parameter | Type | Description |
pointsBalance | number | Player Points |
pointsValue | number | The actual value equivalent to player points. |
currency | string | Store Currency |
pointsName | string | The naming of the rewarding points that appears to the player. |
"points": {
"pointsBalance": 11500,
"pointsValue": 115,
"currency": "USD",
"pointsName": "Points"
}
The referral object is returned in the configurations API response body. It describes the referral program configurations.
Parameter | Type | Description |
referralMethod | string | Defines how the referral program rewards your players, Possible values:
|
eventName | string | The name of the event which is linked to the referral action |
eventMetaData | string | The event metadata which value should be monitored and checked for completing the referral. |
playerReward | object | "playerReward":{
"extraReward":{
"rewardEvery":5,
"rewardType":null,
"score":2,
"point":1,
"voucher":null
},
"rewardType":"Vouchers",
"score":0,
"point":0,
"voucher":{
"voucherType":"Free Shipping",
"productId":"",
"productName":"",
"value":0
}
} An object that defines the referring player's reward. The playerReward object is defined as follows:
|
friendReward | object | Defines the referred player reward configurations in case the referralMethod is "PlayerAndFriend" meaning that the referred player should also be rewarded.The object is the same as the playerReward object excluding the extraReward . |
{
"referralMethod":"PlayerAndFriend",
"eventName":"",
"eventMetaData":null,
"playerReward":{
"extraReward":{
"rewardEvery":5,
"rewardType":null,
"score":2,
"point":1,
"voucher":null
},
"rewardType":"Vouchers",
"score":0,
"point":0,
"voucher":{
"voucherType":"Free Shipping",
"productId":"",
"productName":"",
"value":0
}
},
"friendReward":{
"rewardType":"Vouchers",
"score":0,
"point":0,
"voucher":{
"voucherType":"Free Product",
"productId":"6161866621123",
"productName":"Antique Drawers",
"value":250
}
}
}
Describes any transaction made in your system.
Attribute | Type | Description |
transactionId | string | Unique transaction ID which identifies the underlying transaction in your system, e.g. order number, invoice number. It will be used for reversing any reward or redemption transaction on Gameball. |
gameballTrasnactionId | integer | Transaction ID on Gameball system. |
type | string | Transaction type string. Can be one of the following: AchievementReward PaymentReward Refund Redemption Expiry Cancel Migration ManualAccumulation DiscountCode ManualDeduction ManualReward |
direction | string | Either "+" or "-" indicating transaction was an addition or deduction |
playerUniqueId | string | Player unique identifier used to uniquely identify the player on Gameball. |
points | integer | Number of points involved in the transaction |
amount | number | Monetary amount involved in the transaction |
transactionTime | string | Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: transactionTime is automatically handled when using server-side SDKs.Example: "2019-09-19T16:14:09.895Z" |
merchantName | string | Merchant name for transaction |
branchName | string | Branch Name for transaction |
{
"transactionId":"trx123",
"gameballTransactionId":"gbtrx123",
"transactionTime":"2019-09-21T16:53:28.190Z",
"type":"Cash Back",
"direction":"+",
"playerUniqueId":"1234",
"points":500,
"amount":10,
"merchantName":"merchant",
"branchName":"branch"
}
Last modified 1yr ago