Event

Gameball event API endpoint allows you to record your player's actions in order to track their journey within Gameball widget.
The event APIs help you record any actions your user performs, along with any properties or metadata that describe the action. For further elaboration on events, check this article in our Help Center.
Each action is known as an event. Each event has a name, like place_order, and metadata, for example a place_order event might have properties like amount or source. Calling events  is one of the first steps to getting started with Gameball.
The event API call accepts a collection of event to help tracking multiple user actions. Event object is described in Object Reference.
Events can be sent along with points reward and points redemption using Actions Composite API endpoint.
post
Event
/integrations/event
The API call is used to send an event to Gameball where the received event will be evaluated and counted toward player challenges
Request
Response
Request
Headers
APIKey
required
string
Client API Key
Body Parameters
events
required
object
Collection of player events to be sent to Gameball. 

playerUniqueId
required
string
Player unique identifier used to uniquely identify the player on Gameball.
playerAttributes
optional
object
An object containing all of the attributes of the player.
Player object is described in Object Reference section.
Response
200: OK
Success. 
{}
400: Bad Request
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."
}
401: Unauthorized
Invalid APIKey.
{}
403: Forbidden
APIKey missing. 
{}
In case the player doesn't exist on Gameball before sending the Event API call, the player will be created automatically on Gameball.
Usage Examples
Example One
The below represents events done by a player with playerUniqueId “player123” on two events:
Event “place_order”: (An event that has 2 metadata keys)
total_amount: Total money paid by the player
category: Type of products being bought by player
Event review: (An event with no metadata)
cURL
Node.js
Ruby
.NET
PHP
Python
cURL
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
  "events": {
    "place_order": {    // Events with metadata
      "total_amount": "100",
      "category": [
          "electronics",
          "cosmetics"
      ]
    },
    "review": { } // For events with no metadata
  },
  "playerUniqueId": "player123"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/event'
Node.js
var apiKey = '807b041b7d35425988e354e1f6bce186'
var gameball = require('gameball')
var Gameball = new gameball(apikey)
Gameball.sendEvent({
        "events": {
            "place_order": {
                "total_amount": "100",
                "category": [
                    "electronics",
                    "cosmetics"
                ]
            },
            "review": {}
        },
        "playerUniqueId": "player123"
    },
    function(err, res) {
        if (err) console.log(err)
        else console.log(res)
    })
Ruby
require 'gameball'
Gameball.api_key = "807b041b7d35425988e354e1f6bce186"
Gameball::Event.send_event({
  events: {
    place_order: {
      total_amount: "100",
      category: [
        "electronics",
        "cosmetics"
      ]
    },
    review: {}
  },
  playerUniqueId: "player123"
})
.NET
using Gameball;
using Gameball.Models;
var apiKey = "807b041b7d35425988e354e1f6bce186";
var Gameball = new Gameball(apiKey);
//Creating Request
var request = new EventRequest() {
  PlayerUniqueId = "player123"
};
//Place Order Event			
Event PlaceOrder = new Event() {
  Name = "place_order"
};
PlaceOrder.AddMetadata("total_amount", "100");
PlaceOrder.AddMetadata("category", new string[] {
  "electronics",
  "cosmetics"
});
//Review Event
Event Review = new Event() {
  Name = "review"
};
//Sending Request
request.AddEvent(PlaceOrder);
request.AddEvent(Review);
var send_event_response = Gameball.SendEvent(request);
PHP
require_once('vendor/autoload.php');
$apiKey = "807b041b7d35425988e354e1f6bce186";
$gameball = new \Gameball\GameballClient(apiKey);
​
$request = new \Gameball\Models\EventRequest();
$request->addEvent('place_order');
$request->addMetaData('place_order','total_amount','100');
$request->addMetaData('place_order','category',array("electronics","cosmetics"));
$request->addEvent('review');
​
$playerRequest = \Gameball\Models\PlayerRequest::factory('player123');
$request->playerRequest = $playerRequest;
​
$sendEventresponse= $gameball->event->sendEvent($request);
Python
import gameball
apiKey = "807b041b7d35425988e354e1f6bce186"
gameball.api_key = apiKey
​
request = gameball.eventObject(player_unique_id = "player123")
request.add_event("place_order", {
  "total_amount": "100",
  "category": [
    "electronics",
    "cosmetics"
  ]
})
request.add_event("review")
send_event_response = gameball.send_event(request)
Example Two
The below example shows how playerAttributes object can be sent with the request to create or update player data, while triggering an event:
Event reserve: An event with one metadata key
rooms: Types of rooms booked by player, 1 for standard and 2 for deluxe rooms
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
Node.js
Ruby
.NET
PHP
Python
cURL
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
"events": {
            "reserve": {
                "rooms": 2
            }
        },
"playerUniqueId": "player123",
"playerAttributes": {
    "displayName": "Jon Snow",
    "email": "jon.snow@example.com",
    "dateOfBirth": "1980-09-19T00:00:00.000Z",
    "joinDate": "2019-09-19T21:06:29.158Z"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/event'
Node.js
var apiKey = '807b041b7d35425988e354e1f6bce186'
var gameball = require('gameball')
var Gameball = new gameball(apikey)
Gameball.sendEvent({
        "events": {
            "reserve": {
                "rooms": 2
            }
        },
        "playerUniqueId": "player123",
        "playerAttributes": {
            "displayName": "Jon Snow",
            "email": "jon.snow@example.com",
            "dateOfBirth": "1980-09-19T00:00:00.000Z",
            "joinDate": "2019-09-19T21:06:29.158Z"
        }
    },
    function(err, res) {
        if (err) console.log(err)
        else console.log(res)
    })
Ruby
require 'gameball'
Gameball.api_key = "807b041b7d35425988e354e1f6bce186"
Gameball::Event.send_event({
  events: {
    reserve: {
      rooms: 2
    }
  },
  playerUniqueId: " player123",
  playerAttributes: {
    displayName: " Jon Snow",
    email: "jon.snow@example.com",
    dateOfBirth: "1980-09-19T00:00:00.000Z",
    joinDate: "2019-09-19T21:06:29.158Z"
  }
})
.NET
using Gameball;
using Gameball.Models;
var apiKey = "807b041b7d35425988e354e1f6bce186";
var Gameball = new Gameball(apiKey);
//Creating Request
var request = new EventRequest() {
  PlayerUniqueId = "player123",
  PlayerAttributes = new PlayerAttributes() {
    DisplayName = "Jon Snow",
    Email = "jon.snow@example.com",
    DateOfBirth = new DateTime(1980, 9, 19),
    JoinDate = new DateTime(2019, 9, 19, 21, 6, 29, 158)
  }
};
//Reserve Event			
Event Reserve = new Event() {
  Name = "reserve"
};
Reserve.AddMetadata("rooms", 2);
​
//Sending Request
request.AddEvent(Reserve);
var send_event_response = Gameball.SendEvent(request);
PHP
require_once('vendor/autoload.php');
$apiKey = "807b041b7d35425988e354e1f6bce186";
$gameball = new \Gameball\GameballClient(apiKey);
$request = new \Gameball\Models\EventRequest();
$request->addEvent('reserve');
​
$request->addMetaData('reserve','rooms',2);
​
​
$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = 'Jon Snow';
$playerAttributes->email = 'jon.snow@example.com';
$playerAttributes->dateOfBirth = '1980-09-19T00:00:00.000Z';
​
​
$playerRequest = \Gameball\Models\PlayerRequest::factory('player123' , $playerAttributes);
$request->playerRequest = $playerRequest;
​
$sendEventresponse= $gameball->event->sendEvent($request);
Python
import gameball
apiKey = "807b041b7d35425988e354e1f6bce186"
gameball.api_key = apiKey
​
request = gameball.eventObject(player_unique_id = "player123")
request.add_event("reserve", {
  "rooms": 2
})
request.add_player_attribute("displayName", " Jon Snow")
request.add_player_attribute("email", "jon.snow@example.com")
request.add_player_attribute("dateOfBirth", "1980-09-19T00:00:00.000Z")
request.add_player_attribute("joinDate", "2019-09-19T21:06:29.158Z")
send_event_response = gameball.send_event(request)
Example Three
The below example shows how playerAttributes object including custom attributes object can be sent with the request to create or update player data, while triggering an event:
Event reserve: An event with one metadata key
rooms: Types of rooms booked by player, 1 for standard and 2 for deluxe rooms
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
Node.js
Ruby
.NET
PHP
Python
cURL
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
"events": {
            "reserve": {
                "rooms": 2
            }
        },
"playerUniqueId": "player123",
"playerAttributes": {
    "displayName": "Jon Snow",
    "email": "jon.snow@example.com",
    "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/event'
Node.js
var apiKey = '807b041b7d35425988e354e1f6bce186'
var gameball = require('gameball')
var Gameball = new gameball(apikey)
Gameball.sendEvent({
        "events": {
            "reserve": {
                "rooms": 2
            }
        },
        "playerUniqueId": "player123",
        "playerAttributes": {
            "displayName": "Jon Snow",
            "email": "jon.snow@example.com",
            "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)
        else console.log(res)
    })
Ruby
require 'gameball'
Gameball.api_key = "807b041b7d35425988e354e1f6bce186"
Gameball::Event.send_event({
  events: {
    reserve: {
      rooms: 2
    }
  },
  playerUniqueId: " player123",
  playerAttributes: {
    displayName: " Jon Snow",
    email: "jon.snow@example.com",
    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);
//Creating Request
var request = new EventRequest() {
  PlayerUniqueId = "player123",
  PlayerAttributes = new PlayerAttributes() {
    DisplayName = "Jon Snow",
    Email = "jon.snow@example.com",
    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);
​
//Reserve Event			
Event Reserve = new Event() {
  Name = "reserve"
};
Reserve.AddMetadata("rooms", 2);
​
//Sending Request
request.AddEvent(Reserve);
var send_event_response = Gameball.SendEvent(request);
PHP
require_once('vendor/autoload.php');
$apiKey = "807b041b7d35425988e354e1f6bce186";
$gameball = new \Gameball\GameballClient(apiKey);
$request = new \Gameball\Models\EventRequest();
$request->addEvent('reserve');
​
$request->addMetaData('reserve','rooms',2);
​
​
$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = 'Jon Snow';
$playerAttributes->email = 'jon.snow@example.com';
$playerAttributes->dateOfBirth = '1980-09-19T00:00:00.000Z';
​
$playerAttributes->addCustomAttribute('location' , 'Miami');
$playerAttributes->addCustomAttribute('graduationDate' , '2018-07-04T21:06:29.158Z');
$playerAttributes->addCustomAttribute('isMarried' , false);
​
​
$request = \Gameball\Models\PlayerRequest::factory('player123' , $playerAttributes);
$request->playerRequest = $playerRequest;
​
$sendEventResponse= $gameball->event->sendEvent($request);
​
Python
import gameball
apiKey = "807b041b7d35425988e354e1f6bce186"
gameball.api_key = apiKey
​
request = gameball.eventObject(player_unique_id= " player123")
request.add_event("reserve", {"rooms" : 2})
request.add_player_attribute("displayName", " Jon Snow")
request.add_player_attribute("email", "jon.snow@example.com")
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)
send_event_response = gameball.send_event(request)
Remarks
API consumer can provide any number of events given that each event name is not replicated
API consumer can provide from 0 to all event metadata keys, however the keys must not be replicated. If the consumer has multiple values for a single metadata key it should be provide as an array of strings as follows “key”: [“value1”, “value2”, “value3”, …]
Player
Purchase Rewards
Last updated 5 months ago
Event

postEvent

Usage Examples

Example One

Example Two

Example Three

Remarks

post
Event
