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 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": {}}
The PlayerAttribute object is an object containing all of the attributes of the player.
"playerAttributes": {"displayName": "John Doe","email": "[email protected]","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",}}
Parameter | Description | Examples | Type |
| Player's display name | Fred | String |
| Email address of the player | String | |
| Gender: M or F | M | String |
| Mobile number with country code | 0018320000000 | Number |
| Player's birth date | YYYY-MM-DD | Date |
| Date at which the player joined | YYYY-MM-DD | Date |
| Player's community group | ​ | string |
| Customized data for players added by the client | ​ | Object |
The Level Object is found in the Player Info response body. It contains info about the player's current level.
Parameter | Description | Type |
| Level Name
| String |
| Level Description | String |
| The required score to reach the level. | Number |
| Level Order | Number |
| Logo icon of the level. | String |
| 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/[email protected]","benefits": {"scoreEnteryReward": 0,"pointsEnteryReward": 0,"levelDiscount": null,"discountCapping": null}
The Points Object is found in the Player Info response body. It contains info about the player's points.
Parameter | Description | Type |
| Player Points
| Number |
| The actual value equivalent to player points. | Number |
| Store Currency | String |
| 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"}
​
The Score Object is found in the Player Info response body. It contains info about the player's score.
Parameter | Description | Type |
| Player Score
| Number |
| 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"}
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"}}
Parameter | Description | Required | Type |
| Monetary value that the player will be rewarded for based on the Purchase Reward program configurations. (Amount must be positive). | No | Number |
| Hold reference ID received after calling Hold Points API. | No | 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. | Yes | 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. | Yes | String |
| Hashed body with SHA1 algorithm. As described in Hashing Transaction Message section. Note: hash is automatically handled when using server-side SDKs. | Yes | String |
| Merchant object as described in Object reference section | No | Object |
Holds information of merchant and its branch
"merchant": {"uniqueId": "string","name": "string","branch": {"uniqueId": "string","name": "string"}}
​
Parameter | Description | Required | Type |
| Merchant unique id or code | Yes | String |
| Merchant name | No | String |
| Optional branch information | No | String |
| Branch unique id or code | Yes | String |
| Branch name | No | String |