Player

The player API is responsible for creating players or updating exisitng player informati

Player

POST /integrations/player

The API call is used to create or update a player details in Gameball with the provided attributes

Headers

Name	Type	Description
APIKey	string	Client API key

Request Body

Name	Type	Description
levelOrder	integer	An integer representing the logical order of the configured level. IMPORTANT: manual player leveling is available under special circumstances and is not available by default. Contact us for more info.
playerAttributes	object	An object containing all of the attributes of the player. Player object is described in Object Reference section.
playerUniqueId	string	Player unique identifier used to uniquely identify the player on Gameball.

200 Success.

{
    "gameballId": 4067
}

400 JSON Body Invalid or missing required parameters. The response will include error description payload described in Errors section.

{
    "code": 4,
    "message": "The PlayerUniqueId field is required."
}

{
    "code": 7,
    "message": "No level order was found matching the provided level."
}

{
    "code": 17,
    "message": "Different leveling method required to perform level update."
}

401 Invalid APIKey.

{}

403 APIKey missing.

{}

Response Description

Attribute	Description
gameballId	Player ID on Gameball

Choose an Unchangeable Player Unique ID

Gameball user profile gets created using the playerUniqueId. It is highly recommended to have the unique ID as an identifier that would NEVER be changed. If this unique ID changes for a given player, you risk losing all original data for that player and hence losing their points and rewards on Gameball. Accordingly, it is NOT recommended to use email address or mobile number as the unique ID as both can be changed by the user at anytime.

Usage Example

The example shown is a request sent to Gameball to create a player with playerUniqueId“player123”and with some custom attributes inside the custom Object.

All attributes should be inside the playerAttributes object, if the values of any attributes shown below are unavailable, remove the attribute from the playerAttributes object.

Navigate through different tabs to view the APIs for each language.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
  "playerUniqueId":"player123",
   "playerAttributes":{
      "displayName":"Jon Snow",
      "firstName": "Jon",
      "lastName": "Snow",
      "email":"[e-mail]",
      "gender":"M",
      "dateOfBirth":"1980-09-19T00: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/v2.0/integrations/player'

Node.js

var apiKey = '807b041b7d35425988e354e1f6bce186'
var gameball = require('gameball')
var Gameball = new gameball(apikey)
Gameball.initializePlayer({
    'playerUniqueId':'player123',
    'playerAttributes': {
        'displayName': 'Jon Snow',
        'firstName': 'Jon',
        'lastName': 'Snow',
        'email': '[e-mail]',
        'gender': 'M',
        'dateOfBirth': '1980-09-19T00:00:00.000Z',
        'joinDate':'2019-09-19T21:06:29.158Z',
        'custom': {
         'location':'Miami',
         'graduationDate':'2018-07-04T21:06:29.158Z',
         'isMarried':false
        }
    }
}, function(err, res) {
    if (err) {
        console.log(err)
    }
})

Ruby

require 'gameball'
Gameball.api_key = "807b041b7d35425988e354e1f6bce186"
Gameball::Player.initialize_player({
  playerUniqueId: "player123",
  playerAttributes: {
    displayName: "Jon Snow",
    firstName: "Jon",
    lastName: "Snow",
    email: "[e-mail]",
    gender: "M",
    dateOfBirth:"1980-09-19T00:00:00.000Z",
    joinDate:"2019-09-19T21:06:29.158Z",
     custom:{
         location:"Miami",
         graduationDate:"2018-07-04T21:06:29.158Z",
         isMarried: false
     }
  }
})

.NET

using Gameball;
using Gameball.Models;
var apiKey = "807b041b7d35425988e354e1f6bce186";
var Gameball = new Gameball(apiKey);
PlayerRequest request = new PlayerRequest() {
  PlayerUniqueId = "player123",
  PlayerAttributes = new PlayerAttributes() {
    DisplayName = "Jon Snow",
    FirstName = "Jon",
    LastName = "Snow",
    Email = "[e-mail]",
    Gender = "M",
    DateOfBirth = new DateTime(1980, 9, 19),
    JoinDate = new DateTime(2019, 9, 19, 21, 6, 29, 158)
  }
};
//Adding Custom Attributes
request.PlayerAttributes.AddCustomAttribute("location", "Miami");
request.PlayerAttributes.AddCustomAttribute("graduationDate", new DateTime(2018, 7, 4, 21, 6, 29, 158));
request.PlayerAttributes.AddCustomAttribute("isMarried", false);

var player_response = Gameball.InitializePlayer(request);

PHP

require_once('vendor/autoload.php');
$apiKey = "807b041b7d35425988e354e1f6bce186";
$gameball = new \Gameball\GameballClient(apiKey);

$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = 'Jon Snow';
$playerAttributes->firstName = 'Jon';
$playerAttributes->lastName = 'Snow';
$playerAttributes->email = '[e-mail]';
$playerAttributes->gender = 'M';
$playerAttributes->dateOfBirth = '1980-09-19T00:00:00.000Z';
$playerAttributes->joinDate = '2019-09-19T21:06:29.158Z';
$playerAttributes->addCustomAttribute('location' , 'Miami');
$playerAttributes->addCustomAttribute('graduationDate' , '2018-07-04T21:06:29.158Z');
$playerAttributes->addCustomAttribute('isMarried' , false);

$playerRequest = \Gameball\Models\PlayerRequest::factory('player123',$playerAttributes);

$playerResponse= $gameball->player->initializePlayer($playerRequest);

Python

import gameball
apiKey = "807b041b7d35425988e354e1f6bce186"
gameball.api_key = apiKey

request = gameball.playerObject("player123")
request.add_player_attribute("displayName", "Jon Snow")
request.add_player_attribute("firstName", "Jon")
request.add_player_attribute("lastName", "Snow")
request.add_player_attribute("email", "[e-mail]")
request.add_player_attribute("gender", "M")
request.add_player_attribute("dateOfBirth", "1980-09-19T00:00:00.000Z")
request.add_player_attribute("joinDate", "2019-09-19T21:06:29.158Z")
request.add_custom_player_attribute("location", "Miami")
request.add_custom_player_attribute("graduationDate", "2018-07-04T21:06:29.158Z")
request.add_custom_player_attribute("isMarried", False)

player_response = gameball.initialize_player(request)

Player Info

POST /integrations/player/info

The API call is used to retrieve player's info.

Headers

Name	Type	Description
Lang	string	Preferred language to get your player's info in.
APIKey	string	Client API Key

Request Body

Name	Type	Description
playerUniqueId	string	Player unique identifier used to uniquely identify the player on Gameball.
hash	string	Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section. Note: hash is automatically handled when using server-side SDKs.

200 Success.

{
    "displayName": "Jon Snow",
    "referralCode": "CODE12",
    "referralLink": "https://gameofthrones.myshopify.com/account/register?ReferralCode=CODE12",
    "score": {
        "scoreBalance": 15830,
        "scoreName": "Score"
    },
    "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": {
        "pointsBalance": 46012,
        "pointsValue": 460.12,
        "currency": "EGP",
        "pointsName": "Points"
    },
    "playerAttributes": [
        {
            "name": "Email",
            "value": "[e-mail]",
            "type": "String"
        },
        {
            "name": "MobileNumber",
            "value": "0123456789",
            "type": "String"
        },
        {
            "name": "Gender",
            "value": "M",
            "type": "String"
        },
        {
            "name": "DateOfBirth",
            "value": "09/19/1980 00:00:00",
            "type": "Date"
        },
        {
            "name": "JoinDate",
            "value": "09/19/2019 21:06:29",
            "type": "Date"
        }
    ]
}

400 JSON Body Invalid or missing required parameters. the response will include error description payload described in Errors section.

{
    "code": 11,
    "message": "BodyHashed Invalid"
}

401 Invalid APIKey.

{}

402 Request failed. The response will include error description payload described in Errors section.

{
    "code": 101,
    "message": "No Player with this External ID"
}

403 APIKey missing.

{}

Response Description

Attribute	Description
displayName	Player's Display Name
referralCode	Referral Code
referralLink	Referral URL
score	Score object used to describe the player's score at Gameball. Score Object is described in Object Reference section.
level	Level object used to describe the player's current level at Gameball. Level Object is described in Object Reference section.
points	Points object used to describe the player's points at Gameball. Points Object is described in Object Reference section.
playerAttributes	An object containing all of the attributes of the player. Player Object is described in Object Reference section.

Examples

The example shown is a request sent to Gameball to get a player info with playerUniqueId“player456”and with the hash.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "playerUniqueId":"player456",
   "hash":"7090689dc127ddfbe4a7c2260060afe5e6fc3264g"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/player/info'

Node.js

var apiKey = '807b041b7d35425988e354e1f6bce186'
var transactionKey = '90byuedhb7y37d2bd22ybshsn82'
var gameball = require('gameball')
var Gameball = new gameball(apikey,transactionKey)
Gameball.getPlayerInfo({
        "playerUniqueId": "player456"
    },
    function(err, res) {
        if (err) console.log(err)
        else console.log(res)
    })

Ruby

require 'gameball'
Gameball.api_key = "807b041b7d35425988e354e1f6bce186"
Gameball.transaction_key = "90byuedhb7y37d2bd22ybshsn82"
Gameball::Transaction.get_player_info("player456")

.NET

using Gameball;
using Gameball.Models;
var apiKey = "807b041b7d35425988e354e1f6bce186";
var transactionKey = "90byuedhb7y37d2bd22ybshsn82";
var Gameball = new Gameball(apiKey,transactionKey);

var player_info_response = Gameball.GetPlayerInfo("player456");

PHP

require_once('vendor/autoload.php');
$apiKey = "807b041b7d35425988e354e1f6bce186";
$transactionKey = "90byuedhb7y37d2bd22ybshsn82";
$gameball = new \Gameball\GameballClient(apiKey,transactionKey);

$playerUniqueId = 'player456';

$playerInfoResponse= $gameball->transaction->getPlayerInfo($playerUniqueId);

Python

import gameball
apiKey = "807b041b7d35425988e354e1f6bce186"
transactionKey = "90byuedhb7y37d2bd22ybshsn82"
gameball.api_key = apiKey
gameball.transaction_key = transactionKey

player_info_response = gameball.get_player_info(player_unique_id = "player456")

Attach Tags

POST /integrations/player/tags

Used to attach tags to a Player

Headers

Name	Type	Description
APIKey	string	Client API Key

Request Body

Name	Type	Description
playerUniqueId	string	Player unique identifier used to uniquely identify the player on Gameball
tags	string	Comma separated string of tags to be attached to the player

200

Detach Tags

DELETE /integrations/player/tags

Used to detach tags from Player

Headers

Name	Type	Description
APIKey	string	Client API Key

Request Body

Name	Type	Description
playerUniqueId	string	Player unique identifier used to uniquely identify the player on Gameball
tags	string	Comma separated string of tags to be detached from the player

200