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": "[e-mail]",
    "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	[e-mail]	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/[e-mail]",
        "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
merchant	Merchant object as described in Object reference section	No	Object

Merchant Object

Holds information of merchant and its branch

"merchant": {
    "uniqueId": "string",
    "name": "string",
    "branch": {
      "uniqueId": "string",
      "name": "string"
    }
  }

Parameters Description

Parameter	Description	Required	Type
uniqueId	Merchant unique id or code	Yes	String
name	Merchant name	No	String
branch	Optional branch information	No	String
branch.uniqueId	Branch unique id or code	Yes	String
branch.name	Branch name	No	String