# Events

{% hint style="warning" %}
**Note:** Currently the events are only stored and displayed per user in the dashboard. In the future versions you will be able to filter and generate charts based on those events. \
Until then, you can use MySQL to directly query the database.
{% endhint %}

{% hint style="info" %}
If you want to track, for example, conversions, you should also store a Tag, e.g. `purchased`. This allows you to easily filter those sessions and generate charts.
{% endhint %}

Events allow you to store arbitrary data for a specific session or pageview.\
The main difference between **events** and [**tags** ](https://docs.uxwizz.com/api/tags)is that **tags** are unique strings stored per session, whereas events are complex objects saved per individual page visited.

### UST.addEvent(eventData)

Example:

```javascript
// NOTE: Make sure this code is added AFTER the tracking snippet
UST.addEvent({
    category: 'SHOP', // REQUIRED
    action: 'PURCHASED', // REQUIRED
    label: 'Football Shoes',
    value: 49.99,
    value_secondary: 15.99,
    item_id: 'SHOE123',
    data: { img: "prod/img/shoe.png" }
});
```

#### Input parameters

You can pass those values in the **eventData** argument:

| Parameter            | Type              | Example value                | Info                    |
| -------------------- | ----------------- | ---------------------------- | ----------------------- |
| **category**         | string - REQUIRED | "SHOP"                       |                         |
| **action**           | string - REQUIRED | "PURCHASED"                  |                         |
| **label**            | string - OPTIONAL | "Football Shoes"             |                         |
| **value**            | number - OPTIONAL | 49.99                        | eg. product price       |
| **value\_secondary** | number - OPTIONAL | 15.99                        | eg. shipping costs/tax  |
| **item\_id**         | string - OPTIONAL | "SHOE123"                    | eg. item SKU            |
| **data**             | string - OPTIONAL | { img: "prod/img/shoe.png" } | This can be any object. |

{% hint style="warning" %}
**Data types limits**

* **strings** (**category**, **action**, **label**, **item\_id**) have a **character limit of 128**.
* **numbers** (**value** and **value\_secondary**) are stored as fixed precision decimal numbers. \
  They always have **2 decimals** and a maximum of **13** digits before the decimal.

  Max decimal number format example: **9,999,999,999,999.99**
* The **data** field is stored as a MySQL **TEXT** variable and can have any size (limited by the database engine).
  {% endhint %}

{% hint style="info" %}
**Note:** The **data** field is automatically converted to **JSON** using [**JSON.stringify()**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on the client-side **if** the passed value is not already a string.
{% endhint %}

#### Autofilled values

Those values are automatically added by the server for each event

| Name             | Type             | Info                                                   |
| ---------------- | ---------------- | ------------------------------------------------------ |
| **id**           | UNSIGNED INTEGER | ID of the event                                        |
| **clientid**     | UNSIGNED INTEGER | ID of the client (session)                             |
| **clientpageid** | UNSIGNED INTEGER | ID of the client page (pageview)                       |
| **date**         | DATETIME         | Date and time when the event was added to the database |

{% hint style="info" %}
The events system is loosely opinionated, meaning that you can store values in any way you prefer. The system provides multiple **string** and **number** fields that you populate.

In the future, the value of some of those fields might gain a specific meaning in order to automatically generate and display specific charts. For example, the dashboard could automatically show "Revenue" as being the sum of "value" for events that have the action name "PURCHASED".
{% endhint %}


---

# 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://docs.uxwizz.com/api/events.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.