# Event

## Available Endpoints

| Type     | Description                          | Endpoint            |
| -------- | ------------------------------------ | ------------------- |
| **POST** | [**Track Event**](#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](https://help.gameball.co/en/articles/3468399-understand-your-players-events) 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](#event-object).

## POST - Track Event

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

```http
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**](https://developer.tryreferd.com/api-reference/api-reference/broken-reference) to be sent to **Referd**. |

{% hint style="info" %}
In case the user doesn't exist on **Referd** before sending the **Event** API call, the user will be created automatically on **Referd**.
{% endhint %}

#### `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](https://help.tryreferd.com/en/articles/8668415-create-and-send-events-to-referd).

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

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

#### Sample Request Body

```javascript
{
  "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)

{% tabs %}
{% tab title="cURL" %}

```typescript
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"
  }'
```

{% endtab %}

{% tab title="Ruby" %}

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

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}

{% tab title="Python" %}

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

{% endtab %}

{% tab title=".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);
```

{% endtab %}
{% endtabs %}

#### **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

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Ruby" %}

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

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}

{% tab title="Python" %}

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

{% endtab %}

{% tab title=".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);
```

{% endtab %}
{% endtabs %}

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