Custom Events

The actions you choose to record, counted and valued. Custom events carry a count, an optional sum and duration, and segments, and this section turns them into rankings, movers, trends, and breakdowns.

What a custom event is

A custom event is an action you decide to record: a purchase, a search, a command run, a setting changed, a level completed. Your app names it with a key and sends it through the SDK whenever it happens. Countly counts it, and if you attach a sum or a duration it keeps those too, so an event can carry a value (revenue, points) and a time (how long checkout took).

An event can also carry segments, key-value properties such as the product category or the payment method. Segments are what let you break an event down: purchases by category, searches by result count, errors by screen.

Everything Countly records on its own (sessions, views, crashes, pushes) uses keys that start with [CLY]_. That prefix is reserved; your events are everything else, and this section is about them.

Count, sum and duration

Every event carries three base metrics, and the section derives two ratios from them.

• Count is how many times the event was sent. Every event has it.
• Sum is the total of the values you attached, when you attach any. A purchase event with a sum of 42.5 adds 42.5 to the sum; an event sent without a sum adds nothing.
• Duration is the total of the durations you attached, in seconds, when you attach any.
• Sum / count and Duration / count divide the totals by the count, so they read as the average value and the average duration per event.

Sum and Duration stay empty for events that never carry them, which is most events. Count is always there. Data Manager lets you label the three metrics per event ("Revenue" and "Time to complete" instead of "Sum" and "Duration"), and the section shows those labels wherever the metric appears.

Use Cases

See what drives the product

Find the actions actually taken, and the ones that carry the most value.

1. Open Custom Events. The Overview opens on the selected date range.
2. Top events ranks events three ways: by count, by sum per event, and by duration per event. The first list is usage, the other two are value.
3. Scroll to All events for every event with its count and both ratios; sort a column to rank the whole list, search to find one.
4. Click an event to open it in Glance and see how it trends over the range.

Catch a change after a release

See what a release changed in behavior without building a query.

1. Set the date range to the days since the release; the Overview compares them with the same number of days before.
2. Movers lists the events that rose, fell, or appeared for the first time, with the change and the previous value. A new event is a feature that shipped; a decliner is a regression or a removed path.
3. Click a mover to view it in Glance, turn on comparison in the date picker, and read the previous period drawn alongside.
4. For the why, add a breakdown by a segment you send, such as an app version, or continue in Drill.

Measure a value, not just a count

Some events carry a value: revenue on a purchase, points in a game, seconds to complete a task. Counting them is not enough.

1. Send the value with the event: a sum for money or points, a duration in seconds for time. The SDK call takes both alongside the key and the count.
2. In Glance, pick the event and choose Sum or Duration as the metric, or the ratio Sum / count for the average per event.
3. Compare against the previous period to see whether the average moves, not only the volume.
4. In Data Manager, label the metric so it reads as "Revenue" or "Time to complete" across the section.

Break an event down by a segment

An event's segments answer "which kind": purchases by category, searches by results, errors by screen.

1. In Glance, pick the event and one metric, then open Breakdown and choose a segment. The chart turns into ranked bars, one per segment value, and the table lists every value with its share.
2. With several events selected, the breakdown offers only the segments they all share.
3. Sort the table by share to see concentration; search for one value.
4. Continue in Drill hands the same event, metric, and breakdown to Drill for filters, more breakdowns, and profile-level analysis.

FAQs

Why is an event missing from the list?

Either the app has not sent it yet in this date range, the project reached its event key limit and the key was ignored, or the event is hidden in Data Manager. Check Data Manager first: it lists every key the server has seen, hidden ones included.

Why are Sum and Duration empty for my event?

Because the app sends the event without a sum or a duration. Count is always recorded; the other two only when the call includes them.

What does Sum / count mean?

The average value per event: the total of the sums divided by the number of events. For a purchase event with a revenue sum, it is the average order value.

How do I rename an event?

In Data Manager: give it a display name and a description. The key the app sends stays the same, so nothing changes in the SDK.

Can I see how many profiles triggered an event?

Not here: the section counts occurrences. Drill counts unique profiles for any event, with filters and breakdowns; Continue in Drill from Glance takes the selection there.

Why do my numbers differ slightly from Drill?

This section reads pre-aggregated totals in the project's time zone; Drill reads raw events and can be filtered, bucketed, and zoned differently. Small differences at bucket edges are expected.