Custom events


This document explains how to use custom events; a powerful feature that you may use to send any type of data to a Countly server. Note that this document gives an introduction to why custom events may be useful. For an understanding of how to implement custom events for each SDK, please refer to each SDK's documentation.

Before going further, we suggest you take in more information about how to get the most out of custom events from the Countly dashboard by watching the following short intro video.

Using custom events

Generate personalized SDK code snippets

The Countly Code Generator may be used to generate custom SDK code snippets easily and fast. You may provide values for your custom 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).

Basic structure

The structure of the simplest event object is the same as listed below:

		"key": "Button click",
		"count": 1

The properties below are the only mandatory properties for an 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 a purchase, we can use sumto keep track of it:

		"key": "In app purchase",
		"count": 1,
		"sum": 0.99

Ensure you keep key values (event names) under 30 characters. Otherwise, it will be difficult to read and distinguish different custom event names on the Countly dashboard.

What are some industry-specific custom events to track?

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:


In the Basics section we saw an example In app purchaseevent that had only count and sumproperties. It’s nice to be able to track the total number of purchases and total amount of purchases, however, sometimes we may need more detailed information:

  • What item is purchased more?
  • Which countries were top performers in terms of in-app purchase?
  • Which application version leads to more sales?

Segmentation makes it possible to categorize/label an event in order to answer all these questions and much more. By simply adding segmentation key-value pairs to our event, we can track detailed metrics:

		"key": "In app purchase",
		"count": 1,
		"sum": 0.99,
		"segmentation": {
			"app_version": "1.0",
			"country": "Germany",
			"item": "sword"

An event key may have 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. Don't worry - Countly allows you to change how event names look on the dashboard.

Event duration

Event duration is an optional field that you can add to your events. The property name duris used to do so. The recorded time is in seconds.

		"key": "Level completed",
		"count": 1,
		"sum": 19,
 		"dur": 1432

Can I send custom events without a session?

In cases where you would like to send data via the API, you may want to send custom 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). They are stored correctly, without mapping to a session.

Pretty simple right? Here is some further documentation you might find useful in order to get the best out of custom events:

  • Countly DrillA very, very, very advanced query tool for your custom events
  • Countly FunnelsTrack paths and goal completions inside your app using custom events
Was this article helpful?
0 out of 0 found this helpful

Looking for help?