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.

Event

POST /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

Headers

Name	Type	Description
APIKey	string	Client API Key

Name

Type

Description

APIKey

string

Client API Key

Request Body

Name	Type	Description
events	object	Collection of player events to be sent to Gameball.
playerUniqueId	string	Player unique identifier used to uniquely identify the player on Gameball.
playerAttributes	object	An object containing all of the attributes of the player. Player object is described in Object Reference section.

Name

Type

Description

events

object

Collection of player events to be sent to Gameball.

playerUniqueId

string

Player unique identifier used to uniquely identify the player on Gameball.

playerAttributes

object

An object containing all of the attributes of the player. Player object is described in Object Reference section.

{}

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

{}

{}

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)
1. total_amount: Total money paid by the player
2. category: Type of products being bought by player
Event review: (An event with no metadata)

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'

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)
    })

require 'gameball'
Gameball.api_key = "807b041b7d35425988e354e1f6bce186"
Gameball::Event.send_event({
  events: {
    place_order: {
      total_amount: "100",
      category: [
        "electronics",
        "cosmetics"
      ]
    },
    review: {}
  },
  playerUniqueId: "player123"
})

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);

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);

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
1. 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 -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'

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)
    })

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"
  }
})

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);

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);

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
1. 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 -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'

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)
    })

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
    }
  }
})

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);

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);

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”, …]

PreviousPlayer NextPurchase Rewards

Last updated 3 years ago