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 event
• count 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.

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"
   }
}

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.