Custom events


This document explains how to use custom events, a powerful feature that you can use to send any type of data to a Countly server. Note that this document gives an introduction to how custom events can 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 that you get more information about how to get the most out of custom events from Countly dashboard, using the following short intro video.

Using custom events

Generate personalized SDK code snippets

Countly Code Generator can be used to generate custom SDK code snippets easily and fast. You can provide values for your custom event, or user profile, or just start with basic integration and this service will generate 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 just like below;

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

Below properties are the only mandatory properties for an event;

  • key identifies the event
  • count is the number of times this event occured

If the event is tied to an overall numerical data, such as a purchase, we can use sum to keep track of that;

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

Make sure to keep key values (event names) under 30 characters. Otherwise it will be difficult to read and distinguish different custom event names on 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 can provide more insights for your product.

We have created predefined events and show what kind of insights those events will give you:


In the Basics section we have seen an example In app purchase event that had only count and sum properties. It is nice to be able to track total number of purchases and total amount of purchases but 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 lead to more sales?

Segmentation makes it possible to categorize/label an event in order to answer all those 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 can have unlimited number of 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 wrong event keys as they are sent from 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 like on the dashboard.

Event duration

A optional fielld that you can add to your events is event duration. The property name dur is used for that. 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 want to send data via API, you may want to send custom events without beginning a session. There is no problem to send event data out of a session (e.g without first sending session initialization information). They are stored correctly, without mapping to a session.

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

  • Countly Drill: A very very very advanced query tool for your custom events
  • Countly Funnels: Track paths and goal completions inside your app using custom events
Was this article helpful?
0 out of 0 found this helpful

Looking for help?