Event

This API endpoint allows you to track and send your users' events on your platform to Referd.

Available Endpoints

Type	Description	Endpoint
POST	Track Event	/integrations/event

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 Referd.

The event API call accepts a collection of event to help tracking multiple user actions. Event object is described below.

POST - Track Event

This API call is used to send an event to Referd where the received event will be evaluated.

https://api.gameball.co/api/v3.0/integrations/event

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key

Body

Attribute	Type	Required	Description
playerUniqueId	string	Yes	Unique identifier for the user at Referd
events	object	Yes	Collection of user events to be sent to Referd.

In case the user doesn't exist on Referd before sending the Event API call, the user will be created automatically on Referd.

event Object

The Event object is how you record any actions your users perform, along with any metadata that describes the action. For further elaboration on events check Understand your users' events.

Metadata are extra pieces of information you can tie to events you track. They can be none or anything that will be useful while analyzing the events later. We recommend sending properties whenever possible because they give you a more complete picture of what your users are doing. Every Metadata can be a number, a string or an array of values.

Event and Metadata example:

Event Name	Key	Example Value
buy	product_id	"a123456"
	price	30
	product_category	"fashion"
	product_tags	"men & new_collection"

Sample Event Object

"buy": {
  "product_id": "a123456",
  "price": 30,
  "product_category": "fashion"
  "product_tags": ["men", "new_collection"]
}

Sample Request Body

{
  "events": {
    "place_order": {    // Events with metadata
      "total_amount": "100",
      "category": [
          "electronics",
          "cosmetics"
      ]
    },
    "review": { } // For events with no metadata
  },
  "playerUniqueId": "player123"
}

Usage Examples

Example One

The below represents events done by a user with playerUniqueId “player123” on two events:

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

2. Event review: (An event with no metadata)

cURL

curl --location --request POST 'https://api.gameball.co/api/v3.0/integrations/event' \
--header 'apiKey: 807b041b7d35425988e354e1f6bce186' \
--header 'Content-Type: application/json' \
--data-raw '{
  "events": {
    "place_order": {    // Events with metadata
      "total_amount": "100",
      "category": [
          "electronics",
          "cosmetics"
      ]
    },
    "review": { } // For events with no metadata
  },
  "playerUniqueId": "player123"
  }'

Ruby

Gameball::Event.send_event({
	events:{
		place_order:{
			total_amount:"100",
			category:[
				"electronics",
				"cosmetics"
			]
		},
		review:{}
	},
	playerUniqueId:"player123"
})

PHP

$eventRequest = \Gameball\Models\EventRequest::factory("player123");
$eventRequest->addEvent('place_order');
$eventRequest->addMetaData('place_order','total_amount','100');
$eventRequest->addMetaData('place_order','category',array("electronics","cosmetics"));
$eventRequest->addEvent('review');
$response = $gameball->event->sendEvent($eventRequest);

Python

event = gameball.eventObject("player123")
event.add_event(
     'place_order',
      {
         "total_amount":"100",
         "category":["electronics","cosmetics"]
      })
event_request = gameball.send_event(event)

.NET

var placeOrderEvent = new Event(){
	Name="place_order"
};

placeOrderEvent.AddMetadata("total_amount", 100);
placeOrderEvent.AddMetadata("category", new string[]{"electronics","cosmetics"});

var reviewEvent = new Event(){
	Name="review"
};
var eventRequest = new EventRequest(){
	PlayerUniqueId="player123"	
};

eventRequest.AddEvent(placeOrderEvent);
eventRequest.AddEvent(reviewEvent);

var response = Gameball.SendEvent(eventRequest);

Example Two

The below example shows how the event endpoint could be used to trigger an event to reserve 2 rooms:

1. Event reserve: An event with one metadata key

   1. rooms: Types of rooms booked by player, 1 for standard and 2 for deluxe rooms

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
    "events": 
        {
            "reserve": {
                "rooms": 2
            }
        },
    "playerUniqueId": "player123"
}' -v -i 'https://api.gameball.co/api/v3.0/integrations/event'

Ruby

Gameball::Event.send_event({
	events:{
		reserve:{
			rooms:2
		}
	},
	playerUniqueId:" player123"
	
})

PHP

$eventRequest = \Gameball\Models\EventRequest::factory("player123");
$eventRequest->addEvent('reserve');
$eventRequest->addMetaData('reserve','rooms','2');
$response = $gameball->event->sendEvent($eventRequest);

Python

event = gameball.eventObject("player123")
event.add_event(
     'reserve',
      {
         "rooms":2
      })
event_request = gameball.send_event(event)

.NET

var reserveEvent = new Event(){
	Name="reserve"
};

reserveEvent.AddMetadata("rooms", 2);

var eventRequest = new EventRequest(){
	PlayerUniqueId="player123"	
};

eventRequest.AddEvent(reserveEvent);

var response = Gameball.SendEvent(eventRequest);

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