Gameball Developers Guide
v3.0
Ask or search…
βŒƒK

Player

The Player API can be used to create, update and display players' information as well as attach/detach tags in Gameball. Players are uniquely identified by playerUniqueId.

Available Endpoints

Type
Description
Endpoint
POST
​Create Player​
/integrations/player
GET
​Retrieve Player​
/integrations/player/{playerUnqiueId}
GET
/integrations/player/{playerUnqiueIdl}/balance
GET
/integrations/player/{playerUnqiueId}
/hash
GET
/integrations/player/{playerUnqiueIdl}/progress
DELETE
​Delete Player​
/integrations/player/{playerUnqiueId}
GET
​Challenge Progress​
/integrations/player/{playerUnqiueIdl}/progress/challenge/{handle}
GET
​Player's Coupons​
/integrations/transactions/{playerUniqueId}/coupon
GET
/integrations/players/{playerUniqueId}/referrals
GET
/integrations/players/referrals
POST
​Attach Tags​
/integrations/player/{playerUnqiueId}/tags
DELETE
​Detach Tags​
/integrations/player/{playerUnqiueId}/tags

POST - Create Player

https://api.gameball.co/api/v3.0/integrations/player
The API call is used to create or update a player in Gameball with the provided attributes.
This endpoint could also be used in case of referral. In such case,referralCode of the referring player is to be provided along with the body parameters. So that Gameball understands that the newly created player is being referred.
mobile or email should be sent along with the playerUniqueId in case (only if) your account supports channel merging.
In cases where channel merging is supported, you have the flexibility to identify users by their mobile number or email. For accounts utilizing separate systems for online and offline channels, it's advisable to consider changing the customer's unique ID to either their mobile number or email address for enhanced efficiency.

Request

Attribute
Type
Required
Description
APIKey
string
Yes
Client API key

Body

Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player in your database.
Could be database ID, random string, email or anything that uniquely identifies the player.
mobile
string
No
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player's unique email. (Sent in case your account supports channel merging)
playerAttributes
object
No
An object with set of properties that you want to set for the player. This object also includes a customobject inside for custom attributes.
referrerCode
string
No
Referring player’s referral code. This is used in case of referral, where the player to be created is referred by the player having this code.
levelOrder
integer
No
The level order to place the player in.
IMPORTANT: manual player leveling is available under special circumstances and is not available by default. Contact us for more info.
deviceToken
string
No
The FCM token (Firebase Cloud Messaging) needed for sending mobile push notifications. (Used only in case of mobile app)
osType
string
No*
OS Type according to the mobile device used (if any). Note: Required in case deviceToken is sent in the payload (e.g. "android", "ios")

playerAttributes Object

Parameter
Type
Description
displayName
string
Player's display name.
firstName
string
Player's first name.
lastName
string
Player's last name.
mobile
string
Player's mobile number.
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"
country
string
Country of the player.
city
string
City of the player.
zip
string
ZIP of the player.
totalSpent
float
Total amount spent by player.
totalOrders
int
Total orders by player.
lastOrderDate
date
Last order date.
avgOrderAmount
float
Average order amount.
custom
object
Key value pairs of any extra player attributes.
{"class" : "E2022", "weight" : 78}
{
"playerUniqueId":"player123",
"mobile": "+1234567", // optional (Channel Merging)
"email": "[email protected]", // optional (Channel Merging)
"playerAttributes":{
"displayName":"Jon Snow",
"firstName": "Jon",
"lastName": "Snow",
"mobile": "+1234567",
"email":"[email protected]",
"gender":"M",
"dateOfBirth":"1980-09-19T00:00:00.000Z",
"joinDate":"2019-09-19T21:06:29.158Z",
"country": "Egypt",
"city": "Cairo",
"zip": "18754",
"tags": "VIP,Platinum",
"custom":{
"location":"Miami",
"graduationDate":"2018-07-04T21:06:29.158Z",
"isMarried":false
}
},
"referrerCode": null,
"levelOrder": null
}

Response

Parameter
Type
Description
playerUniqueId
string
Unique identifier for the player at Gameball Note: in case your account supports channel merging, mobile or email could be used instead of playerUniqueId.
gameballId
string
Player's ID at Gameball.
levelsProgress
int
The current progress of player on the level.
level
object
Level object holds information about the player's current level at Gameball.
balance
object
An object that contains all the information about the player's balance.
referralCode
string
Player's Referral Code. Used to refer another player.
referralLink
string
Referral URL.
dynamicReferralLink
string
Referral URL for mobile APPs integrations with firebase.
Sample Response
{
"playerUniqueId": "player123",
"gameballId": 160281869,
"levelsProgress": 0,
"level": {
"id": 17812,
"name": "very Basic ",
"description": "",
"levelStartScore": 0,
"levelOrder": 1,
"iconPath": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.png",
"benefits": {
"scoreEnteryReward": 0,
"pointsEnteryReward": 0,
"levelDiscount": null,
"discountCapping": null
}
},
"balance": {
"pointsBalance": 0,
"pointsValue": 0.0,
"pendingPoints": 0,
"pendingPointsValue": 0.0,
"currency": "USD",
"walletPointsName": "Points",
"totalPositivePoints": 0,
"totalPositivePendingPoints": 0,
"totalNegativePoints": 0,
"totalNegativePendingPoints": 0
},
"referralCode": "QQAF9B02734oKn",
"referralLink": "https://wizardtest123.myshopify.com/account/register?ReferralCode=QQAF9B02734oKn",
"dynamicReferralLink": null
}

Usage Examples

Example One

This example creates a new player at Gameball, using playerUniqueId, playerAttributes with custom attributes.
cURL
Ruby
PHP
Python
.NET
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
"playerUniqueId":"player123",
"mobile": "+1234567",
"email": "[email protected]",
"playerAttributes":{
"displayName":"Jon Snow",
"firstName": "Jon",
"lastName": "Snow",
"mobile": "+1234567",
"email":"[email protected]",
"gender":"M",
"dateOfBirth":"1980-09-19T00:00:00.000Z",
"joinDate":"2019-09-19T21:06:29.158Z",
"country": "Egypt",
"city": "Cairo",
"zip": "18754",
"custom":{
"location":"Miami",
"graduationDate":"2018-07-04T21:06:29.158Z",
"isMarried":false
}
}
​
}' -v -i 'https://api.gameball.co/api/v3.0/integrations/player'
Gameball::Player.initialize_player({
playerUniqueId:"player123",
mobile: "+1234567",
"playerAttributes":{
displayName:"Jon Snow",
firstName: "Jon",
lastName: "Snow",
mobile: "+1234567",
gender:"M",
dateOfBirth:DateTime.iso8601("1980-09-19T00:00:00.000Z"),
joinDate:DateTime.iso8601("2019-09-19T21:06:29.158Z"),
country: "Egypt",
city: "Cairo",
zip: "18754",
tags: "VIP,Platinum",
custom:{
location:"Miami",
graduationDate:"2018-07-04T21:06:29.158Z",
isMarried:false
}
}
})
$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = "Jon Snow";
$playerAttributes->firstName = 'Jon';
$playerAttributes->lastName = 'snow';
$playerAttributes->gender = 'M';
$playerAttributes->email = '[email protected]';
$playerAttributes->dateOfBirth = '1978-01-11T00:00:00.000Z';
$playerAttributes->joinDate = '2021-09-19T21:06:29.158Z';
$playerAttributes->country= 'Egypt';
$playerAttributes->city= 'Cairo';
$playerAttributes->zip= '18754';
$playerAttributes->addCustomAttribute('isMarried' , true);
$playerAttributes->addCustomAttribute('location' , 'Miami');
$playerAttributes->addCustomAttribute('graduationDate' , '2018-07-04T21:06:29.158Z');
​
$playerRequest = \Gameball\Models\PlayerRequest::factory(
"player123",
null, // Mobile (not null according to your channel merging config)
null, // Email (not null according to your channel merging config)
$playerAttributes
);
​
$playerResponse = $gameball->player->initializePlayer($playerRequest);
import gameball
gameball.api_key = "API_KEY"
gameball.transaction_key = "TRANSACTION_KEY"
​
# Initialize Player
player_request = gameball.playerObject("player123",
player_attributes = gameball.playerAttributes(
"Jon Snow",
"Jon",
"Snow",
"+1234567",
"M",
"1980-09-19T00:00:00.000Z",
"2019-09-19T21:06:29.158Z",
"Egypt",
"Cairo",
"18754",
tags="VIP,Platinum",
custom={
'location':"Miami",
'graduationDate':"2018-07-04T21:06:29.158Z",
'isMarried':False
}
)
)
player_response = gameball.initialize_player(player_request)
using Gameball;
var Gameball = new Gameball.Gameball(apiKey: "API_KEY", secretKey: "SECRET_KEY");
​
var request = new PlayerRequest()
{
PlayerUniqueId = "player123",
PlayerAttributes = new PlayerAttributes()
{
DisplayName = "Jon Snow",
FirstName = "Jon",
LastName = "Snow",
Email = "[email protected]",
Gender = "M",
Mobile = "+1234567",
DateOfBirth = new DateTime(1980, 9, 19),
JoinDate = new DateTime(2019, 9, 19, 21, 6, 29, 158),
Country:"Egypt",
City:"Cairo",
Zip:"18754"
}
};
var response = Gameball.InitializePlayer(request);

Example Two

This example is a request sent to Gameball when player with referralCodeβ€œCODE11” successfully refers a new player with playerUniqueId β€œplayer456”. Player attributes are also sent within the same request.β€Œ
Note: All attributes inside the playerAttributes object are optional, if the values of any attributes shown below are unavailable, remove the attribute from the playerAttributes object.
cURL
Ruby
PHP
Python
.NET
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
"referrerCode":"CODE11",
"playerUniqueId":"player456",
"playerAttributes":{
"displayName":" Tyrion Lannister",
"firstName":"Tyrion",
"lastName":"Lannister",
"email":"[email protected]",
"gender":"M",
"dateOfBirth":"1978-01-11T00:00:00.000Z",
"joinDate":"2019-09-19T21:06:29.158Z",
"custom":{
"location":"Miami",
"graduationDate":"2018-07-04T21:06:29.158Z",
"isMarried":false
}
}
}' -v -i 'https://api.gameball.co/api/v3.0/integrations/player'
Gameball::Player.initialize_player({
referrerCode:"CODE11",
playerUniqueId:"player456",
playerAttributes:{
displayName:" Tyrion Lannister",
firstName:"Tyrion",
lastName:"Lannister",
gender:"M",
dateOfBirth:DateTime.iso8601("1978-01-11T00:00:00.000Z"),
joinDate:DateTime.iso8601("2019-09-19T21:06:29.158Z"),
custom:{
location:"Miami",
graduationDate:"2018-07-04T21:06:29.158Z",
isMarried:false
}
})
$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = "Tyrion Lannister";
$playerAttributes->firstName = 'Tyrion';
$playerAttributes->lastName = 'Lannister';
$playerAttributes->gender = 'M';
$playerAttributes->email = '[email protected]';
$playerAttributes->dateOfBirth = '1978-01-11T00:00:00.000Z';
$playerAttributes->joinDate = '2021-09-19T21:06:29.158Z';
$playerAttributes->addCustomAttribute('isMarried' , true);
$playerAttributes->addCustomAttribute('location' , 'Miami');
$playerAttributes->addCustomAttribute('graduationDate' , '2018-07-04T21:06:29.158Z');
​
$playerRequest = \Gameball\Models\PlayerRequest::factory(
"player456",
null, // Mobile (not null according to your channel merging config)
null, // Email (not null according to your channel merging config)
$playerAttributes,
"CODE11" // ReferrerCode
);
​
$playerResponse = $gameball->player->initializePlayer($playerRequest);
# Initialize Player
player_request = gameball.playerObject("player123",
player_attributes = gameball.playerAttributes(
"Jon Snow",
"Jon",
"Snow",
"+1234567",
"M",
"1980-09-19T00:00:00.000Z",
"2019-09-19T21:06:29.158Z",
tags="VIP,Platinum",
custom={
'location':"Miami",
'graduationDate':"2018-07-04T21:06:29.158Z",
'isMarried':False
}
),
referrer_code="CODE11"
)
player_response = gameball.initialize_player(player_request)
var request = new PlayerRequest()
{
PlayerUniqueId = "player123",
PlayerAttributes = new PlayerAttributes()
{
DisplayName = "Jon Snow",
FirstName = "Jon",
LastName = "Snow",
Email = "[email protected]",
Gender = "M",
Mobile = "+1234567",
DateOfBirth = new DateTime(1980, 9, 19),
JoinDate = new DateTime(2019, 9, 19, 21, 6, 29, 158)
},
ReferrerCode = "CODE11"
};
var response = Gameball.InitializePlayer(request);

GET - Retrieve Player

This API call is used to retrieve player's information.
https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}
mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

Request

Header

Attribute
Type
Required
Description
APIKey
string
Yes
Client APIKey
Lang
string
No
Language to get the player info with. If not provided, the response would be in default language.
Note: The language provided should be as per configured languages in your account.
Example: "en", "fr".

Path Parameters

Parameter
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball. Note: in case your account supports channel merging, mobile or email could be used instead of playerUniqueId

Response

Parameter
Type
Description
playerUniqueId
string
Unique identifier for the player at Gameball.
playerAttributes
object
An object with set of player properties defined previously at the player's creation.
referralCode
string
Player's Referral Code. Used to refer another player.
referralLink
string
Referral URL.
dynamicReferralLink
string
Referral URL for mobile APPs integrations with firebase.
level
object
Level object holds information about the player's current level at Gameball.
levelsProgress
int
The current progress of the player on the level.
points
object
The current balance of the player.

level Object

The level object contains info about the player's current level.
Parameter
Type
Description
name
string
Level Name.
description
string
Level Description.
levelOrder
integer
Level Order.
iconPath
string
Logo icon of the level.
benefits
object
An object contains the benefits of the current level of the specified player.
The benefits object is described as follows:
  • scoreEntryReward: Rewarded score on entering the current level.
  • pointsEntryReward: Rewarded points on entering the current level.
  • levelDiscount: Discount rewarded to the player on entering the current level.
  • discountCapping: Maximum order total price that allows the discount to be applied.

Sample Response

{
"playerUniqueId":"player456",
"playerAttributes":{
"displayName":"Jon Snow",
"email":"[email protected]",
"mobileNumber":"0123456789",
"gender":"M",
"joinDate":"09/19/2019 21:06:29",
"tags":[
"VIP",
"Elite"
],
"custom":{
"location":"Miami",
"graduationDate":"2018-07-04T21:06:29.158Z",
"isMarried":false
}
},
"referralCode":"CODE12",
"referralLink":"https://gameofthrones.myshopify.com/account/register?ReferralCode=CODE12",
"dynamicReferralLink":"https://gameofthrones.myshopify.com/account/register?ReferralCode=CODE12",
"level":{
"name":"Gold",
"description":null,
"levelOrder":4,
"iconPath":"https://cdn.gameball.co/uploads/Client 1/[email protected]",
"benefits":{
"scoreEntryReward":0,
"pointsEntryReward":0,
"levelDiscount":null,
"discountCapping":null
}
},
"levelProgress": 0,
"points": {
"pointsBalance": 0,
"pointsValue": 0.0,
"pendingPoints": 0,
"pendingPointsValue": 0.0,
"currency": "USD",
"walletPointsName": "Points",
"totalPositivePoints": 0,
"totalPositivePendingPoints": 0,
"totalNegativePoints": 0,
"totalNegativePendingPoints": 0
}
}

Usage Example

The example shown is a request sent to Gameball to get a player info with playerUniqueIdβ€œplayer456”.
cURL
Ruby
PHP
Python
.NET
curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456'
Gameball::Player.get_player_info("player456")
$playerResponse = $gameball->player->getPlayerInfo("player456");
player_response = gameball.get_player_info("player456")
var response = Gameball.GetPlayerInfo(β€œplayer456”);

GET - Player's Balance

This API call is used to retrieve player's current points balance available for redemption and the corresponding equivalent amount.
https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/balance
mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

Request

Header

Attribute
Type
Required
Description
APIKey
string
Yes
Client APIKey
secretKey
string
Yes
Client Secret Key

Path Parameters

Parameter
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball. Note: in case your account supports channel merging, mobile or email could be used instead of playerUniqueId

Response

Parameter
Type
Description
pointsBalance
integer
Player current points balance.
pointsValue
integer
The player's equivalent monetary value topointsBalance according to your Cashback program configurations.
pendingPoints
integer
Player current pending points. (Not active yet, therefore cannot be used at this moment)
pendingPointsValue