Object Reference

Each object in the API may be given an identifier and will typically be addressable through a URL.

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.

Metadata are extra pieces of information you can tie to events you track. They can be none or anything that will be useful while analyzing the events later. We recommend sending properties whenever possible because they give you a more complete picture of what your users are doing. Every Metadata can be a number, a string or an array of values.

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

PlayerAttribute Object

The PlayerAttribute object is an object containing all of the attributes of the player.

"playerAttributes": {
"displayName": "John Doe",
"email": "example@example.com",
"mobileNumber": "011111111111",
"gender": "M",
"dateOfBirth": "2019-09-19",
"joinDate": "2019-09-19",
"community": "github",
"custom": {
"key1": "value1",
"key2": 180,
"key3": "2019-09-19",
"key4": true //boolean values (true or false)
"key5": "value5",
}
}

Parameters Description

Parameter

Description

Examples

Type

displayName

Player's display name

Fred

String

email

Email address of the player

example@example.com

String

gender

Gender: M or F

M

String

mobileNumber

Mobile number with country code

0018320000000

Number

dateOfBirth

Player's birth date

YYYY-MM-DD

Date

joinDate

Date at which the player joined

YYYY-MM-DD

Date

community

Player's community group

string

custom

Customized data for players added by the client

Object

Level Object

The Level Object is found in the Player Info response body. It contains info about the player's current level.

Parameters Description

Parameter

Description

Type

name

Level Name

String

description

Level Description

String

levelStartScore

The required score to reach the level.

Number

levelOrder

Level Order

Number

iconPath

Logo icon of the level.

String

benefits

Level Benefits Object

Object

The following example shows how Level Object is recieved in the response body.

"level": {
"name": "Gold",
"description": null,
"levelStartScore": 7500,
"levelOrder": 4,
"iconPath": "https://cdn.gameball.co/uploads/Client 1/2cf4b388-f957-4789-8309-5476907c1baeicon-level-gold@2x.png",
"benefits": {
"scoreEnteryReward": 0,
"pointsEnteryReward": 0,
"levelDiscount": null,
"discountCapping": null
}

Points Object

The Points Object is found in the Player Info response body. It contains info about the player's points.

Parameters Description

Parameter

Description

Type

pointsBalance

Player Points

Number

pointsValue

The actual value equivalent to player points.

Number

currency

Store Currency

String

pointsName

The naming of the rewarding points that appears to the player.

String

The following example shows how Points Object is received in the response body.

"points": {
"pointsBalance": 11500,
"pointsValue": 115,
"currency": "EGP",
"pointsName": "Points"
}

Score Object

The Score Object is found in the Player Info response body. It contains info about the player's score.

Parameters Description

Parameter

Description

Type

scoreBalance

Player Score

Number

scoreName

The naming of the score points that appears to the player.

String

The following example shows how Score Object is received in the response body.

"score": {
"scoreBalance": 15830,
"scoreName": "Score"
}

PointsTransaction Object

The PointsTransaction Object is used in the Send Action to allow multiple transaction actions to be done in the same request, the actions that are made depend on the parameters that are sent.

The following example shows how to send a reward action using the PointsTransaction Object

{
"playerUniqueId": "player123",
"events": {
"review": {},
"reserve": {
"rooms": 2
}
},
"pointsTransaction": {
"rewardAmount": 99.98,
"transactionId": "tra_123456789",
"transactionTime":"2019-09-19T16:14:09.895Z",
"hash":"f3437e2919ab9f853c7ccde92f4f2b9a6def42db"
}
}

Parameters Description

Parameter

Description

Required

Type

rewardAmount

Monetary value that the player will be rewarded for based on the Purchase Reward program configurations. (Amount must be positive).

No

Number

holdReference

Hold reference ID received after calling Hold Points API.

No

String

transactionId

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.

Yes

String

transactionTime

Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: transactionTime is automatically handled when using server-side SDKs.

Yes

String

hash

Hashed body with SHA1 algorithm. As described in Hashing Transaction Message section. Note: hash is automatically handled when using server-side SDKs.

Yes

String