This User Guide is for the Events feature of Countly 20.11. To see the Events User Guide for the latest version of Countly, i.e., Countly 22.03, please click here.
This document explains how to use Events: a powerful feature that you may use to send any type of data to the Countly server. Note that this document gives an introduction to why Events may be useful.
SDK Implementation
To understand how to implement Events for each SDK, please refer to each SDK's documentation.
If you are just getting started to define events in your application, make sure to check out the Getting started with SDKs article.
Generating Personalized SDK Code Snippets
You can use the Countly Code Generator to generate custom SDK code snippets easily and fast. You may provide values for your event or user profile, or simply start with basic integration, and this service will generate the necessary code for you to use in your favorite IDE (e.g. XCode or Android Studio).
Understanding Events
Basic Structure
The structure of the simplest event object is as listed below:
{
"key": "Purchase",
"count": 1
}
The properties below are the only mandatory properties for any event:
key
identifies the eventcount
is the number of times this event occurred
If the event is tied to an overall numerical data set, such as the purchase amount in the below example, we can use sum
to keep track of it:
{
"key": "Purchase",
"count": 1,
"sum": 100
}
Ensure you keep key values (event names) under 30 characters. Otherwise, it will be difficult to read and distinguish different event names on the Countly Dashboard.
Most of the basic events in your mobile applications and websites are similar, but some events, specifically for a domain, may provide more insights for your product.
We have created predefined events and shown what kind of insights those events will give you:
Segmentation
In the section above we saw an example of a purchase event that had only count
and sum
properties. It is nice to be able to track the total number of purchases and total amount of purchases, however, so sometimes we may need more detailed information to answer questions like:
- Which item is purchased more?
- Which main categories generate more revenue?
- What is the top selling item in a sub category?
Segmentation makes it possible to categorize or label an event in order to answer all these questions and many more. By simply adding segmentation key-value pairs to our event, we can track detailed metrics:
{
"key": "Purchase",
"count": 1,
"sum": 1000,
"segmentation": {
"Item": "Laptop X",
"Sub Category": "Computers",
"Main Category": "Electronics"
}
}
An event key may has various segmentation key-values and all these segmentation keys will be available from your dashboard the moment you first use them inside your application.
Note that you may be using the incorrect event keys as they are sent from the SDKs, and it may be hard to change them back to another definition. Do not worry, though! Countly allows you to change how the event names look on the dashboard.
Event Duration
Event duration is an optional field that you can add to your events. The property name dur
is used to do so. The recorded time is in seconds.
Countly SDKs also have a concept called timed events to mark the beginning and end of an event to calculate the duration automatically.
{
"key": "Purchase",
"count": 1,
"sum": 1000,
"dur": 3600,
"segmentation": {
"Item": "Laptop X",
"Sub Category": "Computers",
"Main Category": "Electronics"
}
}
In cases where you would like to send data via the API, you can send events without beginning a session. There is no problem in sending event data out of a session (e.g. without first sending the session initialization information). Events are stored correctly, without mapping to a session.
Pretty easy right? Here is some other features you might find useful in order to get the best out of events:
- Countly Drill: A very, very, very advanced query tool for your events.
- Countly Funnels: Track paths and goal completions inside your app using events.
Events Dashboard
Events on the Countly Dashboard allows you to track, analyze, and manage events you set. The section is comprised of four subsections:
- Overview: Gives a quick view of the top five events in the last 24 hours and 30 days. It also allows you to add widgets to report event metrics you need to track for a quick review of your event data-related KPIs.
- All Events: Contains a detailed view of each event's properties and segmentations.
- In-App Purchases: Provides revenue-based metrics based on your defined in-app purchase events. More information about this category is covered in the Revenue Analytics documentation.
- Manage Events: Lets you determine visualization and grouping options for events.
Overview
The Overview is the first screen of Events and as it names implies, it gives a quick review of the most triggered events and of the numerical widgets that will help you keep track of important event metrics. Both the widgets and the timeframes as customizable, making this overview crucial for a first and wide outlook of event data to always keep on top of your related KPIs.
This view shows:
1. Top Events by Count: Lists the 5 most triggered events during the last 24 hours (named as Yesterday on the table) and the last 30-days. Each event is clickable, linking to its corresponding detailed view in All Events.
2. Overview: Contains customizable widgets for each event to track them and compare their trends with the previous period.
3. Time range selector: Lets you apply a customizable data range or time buckets to the data visualized in the widgets.
4. Configure
button: Allows you to edit the widgets and select the properties of the events tracked.
List of All Events
All Events is the main page to go in-depth with your events, analyze, and compare them, as well as obviously see all your current events set up.
This is the true core of Events, where you can:
1. Explore the list of events created. You can also use the search bar for a faster visualization
2. Shows the evolution of the data attached to the selected event in the timeframe selected in the upper-right corner. Depending on the event and its segmentation, a filtering menu will be displayed underneath the event name. Note that the type of segmentation will affect the graphic representation of the data but the count
and sum
properties will stay the same. The representation of the later properties can be toggled on/off for easier visualization.
3. Validate the data that is presented graphically above, as well as download.
4. Go to the Compare screen, which lets you select up to 20 different events and see a graphic comparison throughout a customizable period of time. This is particularly useful when you want to determine if one event triggered another one or if there is a certain date in which certain types of event occur or even recur.
5. Edit events, cutomize views, and group events with Manage Events.
Managing Events
The last category of the Events section, Manage Events gives you the power to manipulate your events from the Countly Dashboard. Keep in mind that creation and changes to events must be managed through the SDK used, and only then will the event be displayed to be edited in this screen.
In the Events tab of this screen, you will see the list of existing individual events, allowing you to change an event's order of appearance, to edit it using the Edit
button, and to hide it from view or delete it altogether using the 3-dot ellipsis menu.
Event Grouping
Similar to the other tab, in the Event Groups tab you can create a manage groups made out from the existing events. This helps visualize events that are highly related as one when compared to other events, as well as it is a practical way of finding and working with events easier when using other plugins.