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.
Type | Description | Endpoint |
POST | /integrations/player | |
GET | /integrations/player/{playerUnqiueId} | |
GET | /integrations/player/{playerUnqiueIdl}/balance | |
GET | /integrations/player/{playerUnqiueId} /hash | |
GET | /integrations/player/{playerUnqiueIdl}/progress | |
DELETE | /integrations/player/{playerUnqiueId} | |
GET | /integrations/player/{playerUnqiueIdl}/progress/challenge/{handle} | |
GET | /integrations/transactions/{playerUniqueId}/coupon | |
GET | /integrations/players/{playerUniqueId}/referrals | |
POST | /integrations/player/{playerUnqiueId}/tags | |
DELETE | /integrations/player/{playerUnqiueId}/tags |
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.Attribute | Type | Required | Description |
APIKey | string | Yes | Client API key |
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 custom object 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") |
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
}
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 | |
balance | object | |
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
}
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",
email: "[email protected]",
"playerAttributes":{
displayName:"Jon Snow",
firstName: "Jon",
lastName: "Snow",
mobile: "+1234567",
email:"[email protected]",
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);
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",
email:"[email protected]",
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);
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.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" . |
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 |
Parameter | Type | Description |
playerUniqueId | string | Unique identifier for the player at Gameball |
playerAttributes | object | |
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 | |
levelsProgress | int | The current progress of the player on the level |
balance | object | The current balance of the player |
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:
|
{
"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,
"balance": {
"pointsBalance": 0,
"pointsValue": 0.0,
"pendingPoints": 0,
"pendingPointsValue": 0.0,
"currency": "USD",
"walletPointsName": "Points",
"totalPositivePoints": 0,
"totalPositivePendingPoints": 0,
"totalNegativePoints": 0,
"totalNegativePendingPoints": 0
}
}
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”);
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.Attribute | Type | Required | Description |
APIKey | string | Yes | Client APIKey |
secretKey | string | Yes | Client Secret Key |
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 |
{
"pointsBalance": 11500,
"pointsValue": 115,
"pendingPoints": 200,
"pendingPointsValue": 2,
"totalPositivePoints": 12500,
"totalPositivePendingPoints": 135,
"totalNegativePoints": 1000,
"totalNegativePendingPoints": 20
"currency": "USD",
"pointsName": "Points"
}
The example shown is a request sent to Gameball to get a player's balance with his
playerUniqueId
cURL
Ruby
PHP
Python
.NET
curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
-H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/balance'
Gameball::Player.get_player_balance("player456")