User profiles


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

You may watch an introduction video to User Profiles below.

User Profiles

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

Starting with User Profiles

User Profiles is available with the Enterprise Edition as a plugin. A server with this plugin always shows all the basic user information, regardless of whether the SDK sends extra custom data or not. Therefore, if you have User Profiles, all you would be willing to do is send custom attributes related to that user, assuming that would ever be needed or 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
  • User timeline (total sessions and total events per day)
  • What the user did during each session

Identified vs anonymous users

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

User interface

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

Searchable fields

You may search on this page by clicking on the magnifier icon. You may only search by using a user's name (e.g. "name & surname") or email.

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

  1. User details & engagement: This box gives an overview of the user’s location, country, username and surname, last seen info, and user picture. Note that if a picture has not been provided, Countly attempts to load one from the Gravatar service, assuming an email address has been provided, or generate an avatar for the user’s initials, assuming a name has been provided. The engagement gauge shows how loyal the user is by computing how much they have returned to the application.
  2. Custom user data: Any data sent alongside the standard data. This data can be in the form of a key-value pair and may contain any type of data (e.g. boolean, string, number, etc.). As data is stored in the sub object named ‘custom’, there are no limitations in naming (as they won’t clash with existing values), apart from the standard MongoDB key limitations not containing a “.” nor starting with a “$”. Therefore, any 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 take you directly to the crash page.

How is the 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 the user use the app in the last 7 days, 1 point for each day, up to 7 points as a maximum

The multiplication of these 3 scores shows your user engagement score result. The maximum result is 280 points or 100% engagement.

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

What is a user ID and what is a UID?

User ID, often referenced to as “device ID” or “ID”, is used to identify a user on that particular device which is sent from the SDK. A UID is the internal ID Countly uses to match a user to their actions, and it is also a shorter ID, which is a better method for several query types. Both (device / user) ID and UID are visible on each user profile. An ID appears as follows: c8711040-7402-4739-bebc-21se13421e0d, whereas an UID looks appears as follows: #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 the server.

Here are some of the actions you may perform 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 may find more information about modifying custom user data in our SDK endpoint specification.

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

Events and sessions tied to the user

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

User Profiles give you detailed information regarding whether a 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 it will say "Not Completed" in one of the funnel steps.

You may also leave a note for a specific user.

Drilling down User Profiles

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

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

Loading data with direct queries

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

This functionality also enables other views to reuse the 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 the User Profile Table view.

Making external queries

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

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

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

Request queries

In some cases, queries 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 the Countly server side to generate queries for us and use its results. This is mostly used in Drill and Funnels, where the user list can generate large lists of user IDs (UIDs) to query.

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

Obviously, a request is only made to the same current Countly server’s /o endpoint. However, it gives full control of passed parameters, meaning a request may theoretically be made to other applications as well. For example, in the case where a client has multiple apps used by the same identifiable users through their internal company ID or something similar. This way you could create a plugin that allows querying users in other apps and matches them to users in the existing app by their 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 the Countly server. Click on this link for the iOS example, and this link for the Android example.

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


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

Countly’s Enterprise Edition also allows sending push notifications to groups of users located in a specific region. You will have to set coordinates in the SDK in order to do so.

The algorithm is quite complicated, so we created a few tables to help you.

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 the city & country set in the SDK, GeoIP CC is city & country determined from the 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
X n/a CC GeoIP CC X
CC X not asked SDK CC X
CC Geocoder LL not asked SDK CC Geocoder LL
LL X X Unknown & Unknown SDK LL
LL CC not asked Geocoder CC 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 the table: SDK data first, then geocoder, then GeoIP. The SDK can disable location services and override any part of location-related data.

When a user explicitly disables location services for your app, you should call the corresponding SDK method as well to respect that user's privacy. Otherwise, Countly will continue to collect and store the 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?