Object Reference

This section provides a list of the objects dealt with using the available API endpoints.

Cashback Object

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
}

Challenge Object

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:

  • "AlwaysVisibile"

  • "NotVisible"

  • "VisibleIfEarned"

icon

string

The icon's URL of the challenge.

availability

object

"availability":{

"minLevel": 4,

"tags": ["VIP"]

}

An object that describes challenge availability to players.

  • minLevel : Minimum required level for the player to be eligible to the achieve the challenge.

  • tags: Array of tags for which the challenge is available.

{
"id":3350,
"name":"view product + tag internal",
"description":"",
"rankReward":3,
"walletReward":10,
"repeatable":true,
"maxAchievement":0,
"type":"EventBased",
"visibility":"AlwaysVisible",
"availability":{
"minLevel":5,
"tags":[
"2nd tag"
]
}
}

Event Object

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 and Metadata example:

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": {}
}

Leaderboard object

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

Level Object

Contains information about the player's current level.β€Œ

Parameters Description

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:

  • rankReward: Score rewarded upon reaching that level.

  • walletReward : Points rewarded upon reaching that level.

  • levelDiscount: The discount amount that the level grants.

  • discountCapping: The maximum value to which the discount is applicable. Example: 10% discount for maximum order price 100 USD

  • others: An array of statement(s) that can be used to describe the benefits of the level.

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

LineItems Object

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

Merchant Object

Holds information of merchant and its branchβ€Œ

Parameters Description

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

Notification Object

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

Score Object

Contains info about the player's score.β€Œ

Parameters Description

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

PlayerAttributes Object

Contains all of the attributes describing your player.β€Œ

Parameters Description

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

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]",
"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
}
}

Points Object

Contains information about the player's points.β€Œ

Parameters Description

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

Referral Object

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:

  • "PlayerAndFriend" denotes that both the referring and the referred player should be rewarded. The referred player also should complete the sign up process and perform a certain action according to your configurations.

  • "PlayerOnly" denotes that only the referring player that should be rewarded after a successful referral.

  • "PlayerAndGuest" denotes that both the referring and the referred player should be rewarded. Referred Player Registration is optional, but he would be rewarded after placing a successful order.

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:

  • extraReward: An object that defines the extra reward the referring player is granted after completing specific number of referrals. "extraReward":{

    "rewardEvery":5,

    "rewardType":null,

    "score":2,

    "point":1,

    "voucher":null

    }

    • rewardEvery:Defines the frequency upon which the referring player is rewarded

    • rewardType : Defines the type of the reward, possible values are:

      • "Vouchers"

      • "Score&Points"

    • score: Score rewarded as an extra reward.

    • points: Points rewarded as an extra reward.

    • voucher: An object that defines the rewarded voucher.

    "voucher": {

    "voucherType":"Free Product",

    "productId":"6161866621123",

    "productName":"Antique Drawers",

    "value":250

    }

  • rewardEvery:Defines the frequency upon which the referring player is rewarded

  • rewardType : Defines the type of the reward, possible values are:

    • "Vouchers"

    • "Score&Points"

  • score: Score rewarded as an extra reward.

  • points: Points rewarded as an extra reward.

  • voucher: An object that defines the rewarded voucher.

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

Transaction object

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