Events

Events were introduced in version 3.5.0. If you are using an older userTrack version you must upgrade it before you can use events.

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.

Events allow you to store arbitrary data for a specific session or pageview. The main difference between events and tags is that tags are unique strings stored per session, whereas events are complex objects saved per individual page visited.

UST.addEvent(eventData)

Example:

// NOTE: Make sure this code snipped 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.

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

Note: The data field is automatically converted to JSON using JSON.stringify() on the client-side if the passed value is not already a string.

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

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 userTrack dashboard could automatically show "Revenue" as being the sum of "value" for events that have the action name "PURCHASED".