# 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**](broken://pages/9GPfdFoiZqbOOfaoiWWI#event-object) 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”, …]


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.tryreferd.com/api-reference/api-reference/event.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.