User profiles


User Profiles is a tool which helps you identify users, their devices, event timeline and application crash information. User Profiles can contain any information that either you collect, or is collected automatically by Countly SDK. User properties can be anything that you want to collect, like phone number, gender, age, campaign, or information which can be tied to user or device. This page also has an event timeline showing what user has done historically in each session. Additionally, funnels inside User Profile show whether a specific funnel is passed by this user, or not.

Below you can watch an introduction video to User Profiles.

User Profiles

User Profiles is the best way to track custom information about your users individually.

Starting with User Profiles

User Profiles is available with Enterprise Edition, as a plugin. A server with this plugin always shows all basic user information, regardless of whether SDK sends extra custom data or not. Therefore if you have User Profiles, all you would be willing to do is to send custom attributes related to that user, if that's ever needed and required.

With User Profiles, it's possible to understand:

  • When and where a user has logged in
  • Which events a user has generated during a specific session
  • Timeline of user (total sessions and total events per each day)
  • What user did during each session

Identified vs anonymous users

By default, data collected by User Profiles are always shown under "Anonymous" tab. If you send more data (e.g user name, demographic details etc) then these users will be shown under "Identified" tab.

User interface

In order to know more about users, User Profiles keeps a list of all users in a table. By default, this table shows user's name and surname, device, total sessions, last seen and total time spent information. Click on a specific bar to sort the table with that feature.

Searchable fields

In this page, you can make a search by clicking on the magnifier icon. You can only search in user's name (e.g "name & surname") or user's email.

If you want to see specific information about a user, click on a user's name. This will open another page, where you see detailed information about that user. Here you can see many boxes with different types of information in it. Below you can see detailed breakdown of those boxes which are located on the left hand side:

  1. User details & engagement: This box gives an overview of user location, country, user name and surname, last seen info, and user picture. Note that if picture was not provided, Countly attempts to load one from Gravatar service if there is an email address, or generate avatar for initials, if name is provided. Engagement gauge shows how loyal the user is, by computing how much he has returned back to the application.
  2. Custom user data: Any data sent alongside the standard data. This data can be in the form of key-value pair and may contain any type of data (e.g boolean, string, number etc). As data is stored in sub object named custom, there are no limitations in naming (as they won’t clash with existing values) apart from standard MongoDB key limitations not containing dot and can’t start with $. Therefore, dot and $ symbols will be stripped from custom keys.
  3. Currently affected crashes: This is the last crash this user has seen. Clicking on the crash will get you directly to the crash page.

How is user engagement score calculated?

On each user profile page, you will see a colorful bar that shows user engagement. It's calculated as follows:

  • Score1: Average session duration in minutes, 1 point per minute up to 2 points as a maximum
  • Score2: Amount of sessions in last week, 1 point per session up to 20 points as a maximum
  • Score3: How many days did user use app in last 7 days, 1 point for each day up to 7 points as a maximum

Multiplication of these 3 scores shows user engagement score result. Maximum result is 280 points or 100% engagement.

On the right hand side, information boxes are grouped so that you can know what a user has been doing inside your app. At the top you see a timeline, where each session and event is recorded. Under that part, you see a session history. This session history keeps are record of all sessions of that user, giving information about session date, time and duration.

What is a user ID and what is a UID?

User ID, often referenced as device ID or ID, is used to identify a user on that particular device which is sent from SDK. A UID is the internal id Countly uses to match a user to actions, and also it is a shorter id which is a better way for several query types. Both (device / user) ID and UID are visible on each user profile. An ID looks like c8711040-7402-4739-bebc-21se13421e0d whereas a UID looks like #78e62.

Modifying and setting user values

Apart from simply setting key/value pairs, Countly also utilizes MongoDB operations to provide a way to modify values on server.

Here are some of the actions you can do with custom user data:

Increase/decrease a value:


Assign multiple values:


Store minimal value between current and provided:


Store maximal value between current and provided:


Set initial value, when it does not exist (do not confuse with $setOnInsert which works only on document creation):

"key6":{"$setOnce":"initial value"}

Push one or more values into array:

//add one value to array

//add multiple values to array

Push one or more unique values into array

//add value to array, if it is already in array, it won't add it

//add values to array, if values is already in array, it won't add them

Remove one or more values from array:

//remove one value from array
//remove multiple values from array

You can find more information about modifying custom user data in our SDK endpoint specification.

Note that by default maximum number of custom properties is 20. This can be changed from Management > Configurations > Drill:

Events and sessions tied to user

Under Session History, you can see Event Timeline. When you click on a session entry under Session History table, corresponding session events are shown in this Event Timeline table. If a crash occurs, this crash information is also shown here, in addition to custom events.

User Profiles gives you detailed information whether user has passed a specific funnel or not. Previously, you should have defined this funnel in order to see it appear here. If the funnel is not completed, then in one of the funnel steps it says "Not Completed".

You can also leave a note for a specific user.

Drilling down User Profiles

Just like Countly Drill, you can also construct queries to filter users. Only apart from Drill, those queries are applied to app users database collection directly, thus providing data about real time user properties (unlike Drill using history data). For example, we can tell how many users are exactly on a specific version of the application.

As displayable result is table of users, there is no need for BY queries, which provide breakdown of specific segment, because it is not possible to display such information here. Other than that, it exactly has all the same functionality and values as in Drill queries for Session.

Loading data with direct queries

As you drill down into user profiles and create queries, you can notice that hash part of URL in your browser changes with it. This enables you to share query with others by link or bookmark the query for further review.

This functionality also enables other views reusing User Profiles table to display specific lists of users by matching specific criteria.

Making a simple user profile query

Simple queries are provided as MongoDB queries in JSON encoded string under the namespaces /users/filter, as for example: /users/filter/{"p":{"$in":["Android"]},"cc":{"$in":["US"]}}

This is used when making drill queries in User Profile Table view.

Making external queries

External queries are just like as simple ones, with one addition: They provide back button, so user can easily return back to previous view, after viewing list of users. It is used under namespace /users/query. For example allowing viewing users of specific campaign or affecting by specific crash can be done with /users/query/{"cmp.c":"social591d50302a0a890d59fe8599"}

After user gets to the view, data based on query is preloaded, but query is not preselected. In most cases it is due to the fact that property is not drillable and thus can’t be preselected.

After going to User Profiles table view, the result works more as a subset, as clients can now apply additional query parameters to segment this subset of users.

Request queries

In some cases queries can become so big, that it would not be possible to query them so easily and encode query in the URL hash. In those cases, we involve Countly server side to generate query for us and use its result. This is mostly used in Drill and Funnels where user list can generate large lists of user IDs (uids) to query.

For this purpose, we use namespace /users/request and provide request parameters as JSON encoded string.

Obviously request is only made to this same current Countly server’s /o endpoint. However, it gives full control of passed parameters, thus theoretically, request can be made to other applications, too. For example, in case where client has multiple apps used, by the same identifiable users, through their internal company id or similar. This way one could create a plugin, to allow to query users in another app and match them to users in existing app by that very same id.


// this 1-liner has been wrapped for better a better view


Sending User Profiles data

If you are a developer, sending data including user profiles is not hard. Each official SDK includes information on how to send user profile related data to Countly server. Click on this link for iOS example, and this link for Android example.


Note that you can take advantage of Facebook integration, using Facebook SDK. This helps you collect detailed user information and send it directly to Countly server.


Among other metrics shown by Countly dashboard, it displays geographical distribution of your users. By default Countly automatically determines user location from IP address using free Maxmind geoip database. In case your application has permission to use location services, you can also set user coordinates to SDK, that would substantially increase accuracy. Or supply your own city & country in SDK if you know them.

Countly Enterprise Edition also allows sending push notifications to groups of users located in a specific region. For that, you have to set coordinates in SDK.

The algorithm is quite complicated, so we created a couple of tables.

Before version 18.01

set in SDK geoip has dashboard city & country geo push notifications
X X Unknown & Unknown X
LL X Unknown & Unknown SDK LL

X - no data available. LL - latitude & longitude. CC - city & country. CCLL - latitude, longitude, city, country.

SDK CC means city & country set in SDK, GEOIP CC is city & country determined from geoip database, etc.

Geoip is a Maxmind free database of IP-addresses -> city / country mappings. Geocoder is a Geonames database of coordinates and corresponding city / country combinations.

Version 18.01

set in SDK geocoder has geoip has dashboard city & country geo push notifications
X n/a X Unknown & Unknown X
CC X not asked SDK CC X
LL X X Unknown & Unknown SDK LL
LLCC not asked not asked SDK CC SDK LL
disabled location not asked not asked Unknown & Unknown X

Fallback priority is as shown in table: SDK data first, then geocoder, then geoip. SDK can disable location services and override any part of location-related data.

When user explicitly disables location services for your app, you should call corresponding SDK method as well to respect user's privacy. Otherwise Countly will continue to collect and store location data of this user during each session based on GEOIP services.

Was this article helpful?
0 out of 0 found this helpful

Looking for help?