Send user events
The SDK enables you to monitor and record user behaviors as events. In this guide, you'll learn to:
Send both custom and predefined events
Build events
Add your own dimensions to events.
Send User Events
To publish an Event, create a UserEvent
, and pass it to publishEvent()
:
By calling build()
on a UserEvent
you are creating an immutable PublishableUserEvent
object, which you can pass to publishEvent()
as often as you need. Calling build()
does not modify the UserEvent
object if you need to modify it again.
If you are interested in whether an event could be successfully sent to the backend, you can await the future returned by publishEvent()
:
As there is no meaningful response to return to your app, the value the future resolves to is not specified by the SDK and may change with different versions of the SDK.
Build a user event
A UserEvent
instance is actually a builder for the event we later send to the backend. You can either provide all parameters via the constructor if you want or you can initialize an empty event and later call setters for the different properties. The only thing you need to create a new event is the name of the event, which may also not be empty (and can later no longer be changed). The following constructors are provided:
The EventDetails
class captures the name of a user event with some additional details. Those are the category
, element
, and action
of the event and can be used to group events together. For example, all events generated by the SDK regarding the session tracking share the category session
.
The value
and unit
can only be provided together and default to 1
and Unit.COUNT
. Alternatively, an event can carry a monetary value instead of a value with a unit. The three dimensions default to the empty string if not specified. You can also set the properties after initialization:
setCount
, setSeconds
, and setMilliseconds
are provided for your convenience if you know an event will always use a specific unit.
Add your own dimensions
You can send additional information along with your events by adding Dimensions.
These Dimensions can be used to group events, enabling you to dive deeper into the specific set of events you are looking for and generate a report out of them.
Here is how to add your event with the additional Dimensions:
Predefined Events
The SDK defines a broad range of event classes with predefined semantics. When creating those events you can specify some predefined dimensions depending on the event. . For example, to track the navigationuser fromconfim purchases of your menu screen to a game screenproduct, you could record the following event:
In the case mentioned above, when using the 'JtPurchaseOptionConfirmEvent', there are four required fields for the event: 'jtItemType', 'jtItemName', 'jtItemId', and 'count'.
Please note that the first three fields are pre-filled dimensions or predefined dimensions, which means they will also be added to the event dimension list. This implies that you can only provide seven additional dimensions. Only the fields with titles starting with 'jt' are considered dimensions.
You can find all our Predefined Events here: Predefined Events
User event restrictions
The following restrictions apply to user events:
The name must not be empty.
Name, action, category, and element must be shorter than 256 characters and can only consist of printable ISO 8859-1 characters (U+0020 to U+007E as well as U+00A0 to U+00FF).
Dimension values must be shorter than 4096 characters and can only consist of printable ISO 8859-1 characters (U+0020 to U+007E as well as U+00A0 to U+00FF).
The value of a user event must be finite (i.e., not NaN or ±Infinity).
If you provide a monetary value, the currency needs to be a 3 letter uppercase ISO 4217 string.
Last updated