This User Guide is for the User Profiles feature of Countly 20.11. To see the User Profiles User Guide for the latest version of Countly, i.e., Countly 22.03, please click here.

User Profiles helps you collect and analyze customer information, and get insights about each and every specific user, including identifying users, their devices, the event timeline, and application crash information. User Profiles may contain any information that is either collected by you, or that which is collected automatically by the Countly SDK. User properties can be anything you would like to collect, such as user photo, name, surname, phone numbers, gender, age, campaigns, or information which may be tied to the user or device, as well as custom data like address or hobbies. 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.

This data helps product managers and marketers understand the application usage information, together with corresponding sessions. This can then be used to analyze the demographic view of your customers and understand their behaviors.

You may watch an introduction video to User Profiles below.

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

How User Profiles Work

This is the general lifecycle of collecting and analyzing user data:

1. First, you collect user information and send it to Countly servers.
2. This information is sent via Countly SDK or User Profiles API.
3. Data is collected and visualized on dashboard

As a result, it's possible to understand user sessions, in-app purchase information, last purchase amount/time, as well as user-specific information. Moreover, once defined, it's possible to understand whether a user passed a specific funnel or not.

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, you can easily send custom attributes related to that user, whenever that may 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

Information Collected from Users

This is a list of data that you can collect from users:

• User name and surname
• City and country
• First and last seen time
• Device information
• App information
• Browser information
• Source channel
• Engagement level
• E-mail
• Organization name
• Gender
• Age
• Total Sessions
• Total time spent
• Last purchase date/time
• Last purchase amount
• Total purchase count and amount
• Any custom key values

Note that collecting data is optional, and depending on the country and the regulations, you may need to obtain end user acceptance.

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 by that feature.

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 will 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 and 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.

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.

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:

"key2":{"$inc":2}

Assign multiple values:

"key3":{"$mul":2}

Store minimal value between current and provided:

"key4":{"$max":10}

Store maximal value between current and provided:

"key5":{"$min":10}

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
"key7":{"$push":"value"},

//add multiple values to array
"key8":{"$push":["value1","value2"]},

Push one or more unique values into array:

//add value to array, if it is already in array, it won't add it
"key9":{"$addToSet":"value"},

//add values to array, if values is already in array, it won't add them
"key10":{"$addToSet":["value1","value2"]},

Remove one or more values from array:

//remove one value from array
"key11":{"$pull":"value"},
//remove multiple values from array
"key12":{"$pull":["value1","value2"]},

Delete property:

//delete property
"key13":""

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, the 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 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, unlike 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 the viewing of 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 drill-able, 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 easily and encode query in the URL hash. In such 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.

Example:

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

/users/request/{"api_key":"388531348bdc55c08263296509e5223b"
,"app_id":"591d50302a0a890d59fe8599","method":"funnel"
,"funnel":"47533d96a55b5132b156a915b77afafe","filter":"{}","period":"30days","users_for_step":1}

Sending User Profiles Data

User properties data can be sent whenever the developer of an application wants to sent them via SDK. They are not bound by session or specific event, so they can be sent whenever required. Countly server will receive user profile information, and store them as app_user properties, with all other information we know about the user.

What changes is that all events and sessions that come after you set those properties, on a granular level, will contain those properties too, such as historical data, like a snapshot of user information.

Let's take a simple example - location: One of the possible user properties could be location. You set a user property to location = France, then user has eventA and eventB, and then you change location to Germany and user again has eventA and eventB. Afterwards, inside the data collected, you will be able to distinguish between eventA and eventB made in France and eventA and eventB made in Germany, as this property - location - would be stored with each separate occurrence of all events.

Note that user properties do not increase datapoint count.

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.

Updating SDK to Send Profile Information

You need to use Enterprise Edition on the server side and latest SDK version. User Profiles plugin is not available in Community Edition server. Any user profile related information from SDK sent to a Community Edition will be ignored.

Geolocations

Among other metrics, the Countly dashboard also 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 and 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

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

SDK CC means the city and country set in the SDK, GeoIP CC is city and 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

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.