- Version 1.0: Initial release
- Version 1.1: Add v13.06 features
- Version 1.2: Add v14.08 features
- Version 1.3: Add v15.08 features
- Version 1.4: Add v16.02 features
- Version 1.5: Add v16.12 features
- Version 1.6: Add v17.05 features
- Version 1.7: Add v17.09 features
- Version 1.8: Add v18.01 features
Countly is world's leading open source mobile and web analytics software, focusing on ease of use, extensibility and feature richness. Countly includes a server, a mobile SDK (for mobile analytics), or a web SDK (for web analytics), all of which you can freely use in your own company for your applications under license terms.
Before going deep inside on Countly, here is an introductory video you can watch to get an understanding of how Countly works.
The server part of Countly consists of a service that runs on port 80 (HTTP) or 443 (HTTPS), allowing the system administrator connect to the user interface and get insights about applications tracked. The mobile part consists of SDKs for different smart phones, tablets and desktop operating systems (Windows and Mac OS X). Similarly, web SDK is used to track web page activity throughout the website. In order to start tracking your application, you need to do the following:
- Choose your Linux edition (e.g Countly Community Edition or Enterprise Edition), by looking at comparison table.
- Install the server application so it’s ready to collect data or use a preinstalled server.
- Implement SDK in your application for mobile analytics.
- Put the application in your device and test, or, visit your web application so it starts sending data.
- If tests are successful, send the application to Appstore/Google Play.
Mobile and WEB SDK installation
This guide is all about an introduction to Countly. It expects that you already integrated mobile or web SDKs in your mobile or web environment, or ready to integrate.
After all steps are completed, you are ready to get insights from Countly dashboard. Installation of the server and using SDK is explained in documents you can find on the navigation bar on the left, and won’t be covered here again.
Topics not covered
Since Countly is quite a big and extensive product, we have explained many features in their respective pages and left the basic dashboard usage here.
Other features that you may want to read in detail are as follows:
- Crash reporting
- Push notifications
- Revenue analytics (Enterprise Edition only)
- Flows (Enterprise Edition only)
- User profiles (Enterprise Edition only)
- Funnels (Enterprise Edition only)
- Attribution Analytics (Enterprise Edition only)
1. User interface overview
Countly provides a dashboard for a quick glimpse of the latest status of application usage. You will immediately notice that dashboard is divided into logical sections, mentioned below.
- Navigation bar
- Top bar
- Real-time panel
- Quick date selector
- Analytics panel
Real-time users panel is only available with Enterprise Edition.
Revenue analytics panel is shown (seen) only a custom event is selected for revenue analytics. For more information about how to define a custom in-app purchase event, see Revenue Analytics documentation.
Let’s have a look at each component.
At the top of the navigation bar, you’ll see a list of applications. Each can be selected at once, and dashboard will adopt itself showing the numbers for the selected application. Dashboard is the initial view, and Analytics menu includes several other views that can be of interest, including detailed carrier, country, user retention and session frequency metrics. User and application management is also carried out using links here.
Countly dashboard can adopt itself for different app types
When you track different types of applications (e.g mobile or web), Countly can modify its user interface according to the type of the application viewed. For example when a mobile app is used, only plugins related to mobile apps are shown. Dashboard also shows mobile app related metrics. Similarly, when a web application name is chosen, then dashboard again modifies itself so it doesn't show mobile related analytics.
Here you can select application and dashboards (dashboards is available with Enterprise Edition). Also you can get insights via Countly Assistant, which is designed to give you easy to consume insights about your applications, such as active user changes over weeks and top entry/exit points for web. It’ll also give you information about features you are not taking advantage of, e.g new Countly releases and latest news from Countly team.
On top bar, when you click on Dashboards, you'll see all previous dashboards that you have defined, or "Create a dashboard" action item if you haven't defined one yet.
Here, you can create as many dashboards as you want. Your dashboard can hold several, real-time widgets for multiple applications. You can change the appearance of your dashboard by changing the theme and you can share your dashboard with other Countly users.
And the best part is, you can enable full screen TV mode for your dashboard and all widgets will expand and change appearance for you to be on top of all the metrics that are important for your business at all times.
This feature is only available for Enterprise Edition.
At the very right hand side of this part, you can see the current user icon where you can define password, reach current documentation, get support or logout from Countly.
Have you ever wondered how many users are currently using your application at that moment? This tiny but powerful widget shows you exactly this: online users and newcoming online users. There's also a live, flowing chart on the right hand side that shows the status of your users - you can easily have an insight about whether number of online & new users are increasing and decreasing.
This feature is only available for Enterprise Edition.
Quick date selector
On the top right of the screen you’ll see a list of days. Here, you can either use a defined time frame, or select a date from time selector. Note that if you select a time here, it’ll be automatically selected as you click on other natigation links (e.g Users, Carriers, etc). In order to select a date, click on the selector, then start and finish dates and click on Apply. Graphs and corresponding boxed widgets will automatically be updated.
This panel gives a brief overview of what’s happening on the dashboard. On the top, there are 6 widgets. When clicked, the chart under these widgets are automatically refreshed to show relevant data group.
Each widget shows the following:
- Total sessions: Number of times your application is opened. Click this item to see a time series representation of total sessions.
- Total users: Number of unique devices your application is used from. Click this item to see a time series representation of total users.
- New users: Number of first time users. Click this item to see a time series representation of new users.
- Time spent: Total time spent for your application. Click this item to see a time series representation of average time spent per user.
- Average time spent: Total time spent using your application divided by total user count. Click this item to see a time series representation of average time spent per user.
- Average requests received: Number of write API requests Countly Server received for this application divided by total user count. Click this item to see a time series representation of average events per user.
For each time series chart, there is a light gray and dark gray line. Light gray line shows the previous time frame for comparison purposes.
- Click on 7 days and light lines will show stats between -14 days & -7 days.
- Click on Today and light lines will show stats for yesterday.
- Click on Apr and light lines will show corresponding days of March.
Below the chart, there are 4 black widgets that show the top platform (e.g Android or iOS), top resolution, top carrier as retrieved from device and top users. If you move your mouse over the line graphics here, you’ll see that data will change and show you 2nd and 3rd larges data source (if exists).
Viewing web analytics
When analytics data of a web page is viewed, this page also modifies itself so it shows
Top Sources instead of
Top Resolution and
Top Browser instead of
Top Carrier. For more details, see screenshot below.
Under black widgets, there’s a colorful world map showing which countries use your application more. The greener a country, the more your application is used in corresponding geographic area. On the left to the world map, you’ll see a list of countries (top 7) where your application is used most. Each number next to a country name shows the total number of session.
2. Getting in-depth analytics
Countly’s dashboard provides a quick analysis and gives a glimpse of how your application is performing. It’s mostly useful for marketing people with an intent to understand what’s going on immediately.
Navigation pane on the left gives more detailed information about users, sessions, countries, carriers and more.
Before going forward with each menu item on analytics menu, here is a short intro video showing analytics menu items:
Below we’ll have a look at each menu item.
Users (mobile + web)
Users tab is one of the most important part of the analytics. Here you’ll see an overview of total, new and returning users based on day. This is the menu you’ll need to keep track of most. This tab will give you the answer to the question "How many users do I have?"
Sessions (mobile + web)
If the user opens an application, it counts as a session until he closes it. This menu shows an overview of sessions, together with total sessions, unique sessions and new sessions, broken into time. This menu will give you the answer to the question "How many times your application is opened?"
Countries (mobile + web)
This menu gives an overview of which countries your applications are used most. Table below the world map total users, total sessions and new users. This menu will give you the answer to the question "Where do my users connect from?"
Devices (mobile only)
In this menu, you’ll see 3 main blocks of device information. On the top, there’s a list of devices, and at the bottom, these devices are shown in a table. In the middle, there are 3 blocks of information, showing top platform, top operating system version and top resolution, respectively. Try hovering on each color line and you’ll see other top information.
This menu will give you the answer to the question "Which smartphone types do my users have?"
Resolutions (mobile + web)
This menu shows two pie charts - total users and new users in terms of device resolution (width x height). This screen is important as it gives insights about which resolutions are used most so you can focus on these screen types.
Densities (mobile + web)
Both Android and iOS devices have screen densities and this menu shows densities reported by device. For web, it shows devicePixelRatio, which returns the ratio of the resolution in physical pixels to the resolution in CSS pixels for the current display device.
Application versions (mobile + web)
This page shows different versions of applications, in case they are defined. A stacked chart shows totel sessions and new users. The table under the chart shows total sessions, total users and new users, respectively for each application version. This menu will give you the answer to the question "How do my application versions compare?"
Carriers (mobile only)
Carriers page shows a table of all carriers, together with total sessions, total users and new users for a given period. On the top of the page, there are two pie charts; showing total users and new users of top carriers. There are only 3 carriers shown in this chart for compatibility, so refer to the table for a detailed carrier breakdown. This menu will give you the answer to the question "Which operator do they use?"
Platforms (mobile + web)
Countly provides an intuitive interface to show how different platforms (operating systems) perform. If you use the same app key (Management > Applications), then it’s possible to aggregate this information and see it under this menu.
This menu will give you the answer to the question "Which operating systems do my users have?"
Browsers (web only)
This section shows which browsers visitors are using while visiting your web. Pie chart on the left shows total visitors from each browser. Pie chart on the right shows new visitors from each browser. The table below charts shows a breakdown of this data for each browser.
Sources (mobile + web)
This plugin shows a list of appstores that app is installed from when a mobile app is viewed, and a list of web pages visitors have been referring from.
Pie charts show total users or new users coming from an appstore or referral URL. Table below those charts show a breakdown of this data for each source/appstore. Click on each line on a table to see a list of paths when viewing a web app.
Languages (mobile + web)
This section shows either the language of the browser, or language of the operating system for mobile.
Views or page views (mobile + web)
This menu item shows all web page views of an application. It provides information about total users, new users, total visits, as well as average time spent on each web/mobile page and how many people landed to, and exited from those pages.
More features available with plugins
Countly has a plugin architecture, which helps you get more features and benefits from Countly itself. For example,
Page Views plugin (for web apps) helps see each page average visit time, landing and exit percentages, bounces and page visit durations. Likewise,
Sources plugin (for mobile apps) shows all appstores a mobile app is installed from. Plugins are available via Management > Plugins menu.
3. Engagement view
This menu includes submenu items related with user engagement (retention, loyalty, session frequency and session duration).
User retention (mobile + web)
Retention is condition of keeping your customers. This page shows you active days (e.g days your customer used your application) after first session. On the top right corner, you can have a breakdown of daily, weekly and monthly retention.
Enterprise Edition only
User retention module is only available with Enterprise Edition
One of the most important metrics of calculating user loyalty is retention graphs. With retention graph, you can calculate whether you have one shot users, or are they really coming back to your app after first installation. Usually when we speak about retention, as an industrial standard it’s better mentioning day 1, day 3, day 7 or day 30 retention. It’s hard to see a number between given. For example, day 1 means 1 day after the start date of the retention graph.
Below you can watch a video showing how retention works.
As an example, if you see 2000 users on day 1 (100%), and then if it drops to 1000, then day 1 retention is 50%. Then probably you’ll see 200 users only on day 7, which means 200 users out of 2000 has come back on that particular day. You should read “day 7” retention not like “7-day retention”, as “day 7 retention” exactly shows you how many % of users used your application on day 1 and then day 7.
Note that there are two ways to calculate retention: absolute and relative. For example, user has his first session on 24th of November as 23:00. And then he has next session on 25th of November 01:00. Here, only 2 hours passed. For absolute retention, this counts as +1.
Countly calculates relative retention. This means, Countly would only count +1 day if session would happen after >24 hours but less than 48 hours after first session. For the example above, Countly doesn't count this user as a retained user after 1 day.
User loyalty (mobile + web)
User loyalty shows how many users started a specific number of sessions. Table shows number and percentage of each loyalty group compared with number of sessions (e.g one session, 2 sessions etc). As an example, if you had 10 new users today, they will all be grouped under "first session".
This feature will give you the answer to the question "How many users started a specific number of sessions?"
Session frequency (mobile + web)
Session frequency shows how often do you see your mobile users open your application. It can be used to calculate the trend - or how often your application is used during a given period of time. The session frequency graph is very straightforward - here you’ll see a breakdown of number of sessions and corresponding number and percentage of users for each group. Most of the time, you’ll see that many users will be accumulated in “1st session” and “2nd session” row.
As an example, 1-24 hours bucket shows users who had a next session within less than 24 hours after their previous session.
This menu will give you the answer to the question "How often do you see your users open your app?"
Session durations (mobile + web)
Session Durations view shows users categorized into predefined session duration buckets. In this view, your users are categorized into one of 0-10 seconds, 11-30 seconds, 31-60 seconds, 1-3 minutes, 3-10 minutes, 10-30 minutes, 30-60 minutes or > 1 hour according to this session duration.
This screen will give you the answer to the question "How long do my users stay inside my application?"
For more information, here is a video overview of session durations:
Slipping away users (mobile + web)
Slipping away users show which users are logged in last time. When logged in, it shows number of users together with percentages who haven't had a session for more than 7, 14, 30, 60 and 90 days. It also shows which users have been slipping away individually when User Profiles plugin is activated (User Profiles is available only with Enterprise Edition).
Below you can watch a video about Slipping away users plugin:
This plugin shows how many users give which ratings to your application. This plugin accessible as Rating under of Engagement menu. In order for this plugin to show data, iOS and Anroid SDK or (for web use case) Web SDK should be configured, so that it shows a popup (shows a feedback sticker for web) to end users, and they start sending rating data to Countly server.
DBViewer is a plugin which allows you can explore all Countly MongoDB collections through the user interface. You can filter documents, export results as CSV, XLS or JSON and also you can take advantage of the powerful REST API Database Viewer exposes.
When you first click on
Management > DB Viewer, you will be greeted with the screen below:
Here, there are 3 panes that you may check with:
1) Application selector: Here, you may want to choose all application collections, or only choose one application, and corresponding database collections will appear. 2) Collections: Those are all collections for all apps or a specific application. 3) Documents or database selector: When you first open DB Viewer, you need to select a database here. When you select one, you will further see documents query results.
Community Edition has only one database (countly), and Enterprise Edition has two databases (countly and countly drill). Drill database also stores raw data which is required for detailed segmentation of events, views, crashes, user profiles and such.
When you want to make a query, first select a database and select the application. You can also filter within the collections. Once you select a database (e.g countly or countly drill), you will see the query options to choose from.
DB Viwer also has an API. You can export data using this API. For more information, please refer to those blogs:
There is an input for your database queries which contains JSON validator.
Users can easily select custom fields with projection feature for result data of their queries.
Users can select sorting parameter and sorting type by ui.
Users can separate their collections by application with filter dropdown or search with collection filter input.
View frequency shows views per session (for a mobile app) or visit (for a web app). So if for example there are 120 visitors having between 1.7 views per visit on average, then you will see on the first line that it will write 1-2.
Change in name for View Frequency
Starting from version 16.06, View frequency is renamed to “Views per session” for mobile and “Views per visit” for web.
Times of day
This plugin can visualize to check the busiest times and days. When you click on this plugin, you will see a visualization table including 0-23 (for hours) and Monday-Sunday for weekdays. Each blue dot represent a session and the bigger & intenser a blue dot is, the more users have been using your application or visiting your site.
You can also view this graph as a table. It is possible to view data collected till now, or last 3 months, previous month or this month.
Countly benefits from custom events. It helps product developers and user experience specialists get an understanding how how their application performs, by sending data from inside the application and analysing this information. Just like other information retrieved, custom events are true real-time with Countly, so you don't have to wait for hours for visualization to appear in dashboard.
Events can be compared for a particular application. In order to compare events, click on "Compare" button on event navigation. Here you will be able to each event to be compared. Select as many events as you want, and click on "Compare" button.
Click on the gear icon when viewing the events opens up events configuration menu. In this menu you can remove a list of events, or one by one, and also change how wording of sum, count, etc is viewed.
This screenshot explains possible configurations.
5. Managing and monitoring applications, system and users
Countly provides a user interface to manage and monitor applications, system and users. Most of this functionality comes from plugins, and some of the plugins may be disabled as Countly is installed. In this case, go to Management > Plugins and choose the type of plugin you want to enable, and then corresponding plugin will be enabled in less than 10 seconds.
For more information about plugins, see this page.
Applications can be managed by global users (more information later). To add a web, mobile or desktop application, follow the steps below:
- Go to
Management > Applications
- Click “Add”
- Enter your application name, type, the time zone you are in, and application icon.
- Click “Add Application”
You’ll be given an app key which is unique to that application. This key should be written in the SDK code snippet which in turn will be embedded in your application - please see SDK integration guides on how to do it.
If you sell items from your mobile or web app, you can enter your IAP Event Key in order to collect IAP revenues and see it immediately in your dashboard.
If you want to delete an application, simply click on “Delete”. There may be some cases where you only want to delete all data associated with an application, but keep the application keys and other information. In this case, use “Clear data” to remove all incoming data from this application and start fresh.
Note that if you clear data using this method, certain application configuration like push credentials and attribution configurations are not removed.
It's also possible to modify app related data, after app is created, e.g app name, type, key, etc. In case this application is going to receive push notifications, make sure you add necessary GCM/APN credentials as well.
Countly Code Generator
If you want to generate mobile or web code for custom events, user profiles, crash reporting and all other features that comes with Countly in general, we suggest that you use Countly Code Generator, which is a point and click service that builds necessary code for you.
Countly provides a way to manage different types of users (e.g global admin, admin or user). Each user will be able to do that’s assigned to them. For example, you may want your marketing team to be able to see the whole dashboard, whereas the website manager, as the global admin, can easily add/remove applications, define other users and manage whole interface.
Different types of users have different authorization levels:
- Global admin can add/remove/edit users, add/remove/edit applications and typically can do whatever is assigned them on the user interface. This is the most powerful user.
- Admin can manage applications, e.g add an application, edit it or remove it completely from the management dashboard.
- User is basically at the bottom of the hierarchy, and can only see the dashboard, without having the ability to manage other applications and users.
All 3 types of users can send push notifications, are able to download raw data and use API to read data from MongoDB directly.
This document explains Countly feature permissions per role in detail.
In order to add a user, you must be global admin. Click “Create a new user” to have a drop-down menu where you can enter user information and credentials. Fill in the details here and click “Create user”. Editing a user is straightforward - go to the user row, and click. You’ll be presented with an editable form.
Users can be restricted to only view certain parts of the dashboard as well. In order to restrict parts of dashboard to admins and users, click on "Section access" and you'll see a popup similar to this.
By default, a user has access to all sections (menu items). If admin clicks on a button under
Restrict and click
Done, then corresponding menu item won't be available for this user.
Active Directory integration
When you use AD integration for Enterprise Edition, user and group management is completely hidden, and all management is carried out by AD rules.
The control of users and groups is a core element of Countly Analytics. While you can define a user without a group, you can also define a group and put each user into that particular group to benefit from easy administration if number of users are more than 20. A group helps administrator to create a group, define what users in that group do, and then add users accordingly. In this case, each user may or may not belong to a group.
In order to define a group, go to Management > Users and define your first group here.
Then, you should define particular properties of this group, like, which apps will those users will access to, or which sections they will be able to view. While you create, you can also define which users will be in this group - or, you can do this later, per user.
After you create your group, it will look like this:
Here, we have defined 4 different groups. You can define as much groups as you want, depending on your granularity requirements. After creating a group, when a new user is added, those groups are viewable under "User Groups", as shown below.
Countly plugins have the ability to help you view different types of logs. Most important plugins that come with Countly are:
- Server logs plugin (available under Management): Shows errors occurring during server boot or run.
- Audit logs plugin (available under Management): Shows who has logged in, when was a configuration made and other details.
- Request logs plugin (available under Utilities): Shows each event, together with when it happened from which device and other details. Note that this is used for debugging purposes since it shows only last 1000 events for a particular application.
Sending email reports periodically
Countly can send email reports to you or your colleagues periodically. In order to do this, go to
Utilities > Email reports and you'll see a page where you can define email reports for Analytics, Crash or Push related data.
Below you can watch an intro video showing how to define and configure email reports.
Sending alerts when there is a problem
We know that our customers are too busy to execute their businesses. We know that they can’t be online for all day and every minute. But we also know that their products are used by customers every minute and all day. That’s why getting information about immediate changes in product is very critical in some moments.
Getting access to data on-demand via beautifully crafted reports and dashboards is great and what we excel in. However, you sometimes need to be on top of changes in important metrics even if you aren’t looking at your dashboard.
Alerts plugin helps you to define conditions on session, custom event, crash analytics related metrics and you’ll receive a notification email when a particular condition is met.
You can use view your alerts or define an alert from
Utilities > Alerts.
Alerts can let you know, in general, if there is something that needs your attention. Alerts give you an easy to use mechanism to be notified about changes in your data such as an increase/decrease in new users, occurrence count of a custom event or new crashes/errors.
There are times when there is too much data that your instance keeps. In such situations, segmenting data via Countly Drill or calculating steps via Countly Funnels can take time. Instead of making you wait, Countly tells you that a particular process will be backgrounded. You will be re-notified when corresponding task gets done.
A few things to consider as you use Report Manager is as follows:
- Report manager is available for Enterprise Edition customers since it is used by Drill and Funnels.
- When you go to Drill or Funnel, and when your queries in those two sections take more than 30 seconds (which is configurable under
Management > Configurations), a popup will appear, saying that this task will switch to Report Manager.
- Report Manager handles this task in the background, silently.
- When system is done completing the task, you will be notified with another popup. Now you can view the report under
Utilities > Report Manager.
If you try to view the same report again, you will be notified with a warning since it is already being processed.
Report Manager can also be used to filter different reports that have been run earlier. You can select type (e.g Drill or Funnels), or status (Running, Re-running, Completed or Error).
Report Manager, available under Management, can be also used to view, re-run or delete reports that have been previously:
Populating dashboard with sample data
Sometimes you may want to understand how dashboard looks and works with some sample data. In this case, if it is not already enabled, enable Data Populator plugin (under
Management > Plugins) and run. Chances are it's already enabled - in this case run the plugin under
Utilities > Populate Data.
Countly has a plugin based structure where you can add or remove as many plugins as you want. When clicked on
Management > Plugins, you will see a list of plugins, whether they are enabled or disabled, definition of each and corresponding home pages. Here you can enable or disable each plugin and when you press "Apply", changes will take affect.
Countly allows to write your own plugins and extend Countly functionality, both for Community edition and Enterprise Edition. Dashboard also allows you to upload your plugin, using
Add plugin button. Clicking this button, you will be prompted with a pane so that you can just drag and drop your plugin. This eliminates to upload a plugin using SFTP or other means.
Sometimes, for different reasons, you may want to block particular event or session data to be written to database. In such cases, Filtering Rules plugin come to rescue.
You can add as many rules as you want, e.g based on IP, country, browser, platform etc. You can also filter based on sessions or events.
Changing interface language
Countly is available in several languages, including German, Spanish, Turkish, Italian, Dutch, Russian, Chinese and more. You can easily switch language from the menu on top right, inside the top bar. Click on the language button - there you'll see available languages.
If you want to help with localization in your own language, go to Transifex Countly project page and register yourself to be a contributor to make Countly better localized.
In order protect API key you can use tokens. You can create Tokens under Management > Token Manager. Tokens can be restricted to work only on specific API endpoints, or have limited amount of usages or time. Tokens can be also deleted to stop access.
Token manager can be found in the user menu. (Menu opens when clicking on user icon in the top left side). In this section you can see all created tokens.
There is table describing tokens:
|Table row||Row description|
|Description||Token description (if there is one set) and token value|
|Valid until||Date and time when token expires. If token never expires there is text: "No expiry"|
|Multiple times||States if token can be used multiple times. If not - token expires after first use.|
|App||List of Apps, which can be accessed with this token. Value "All apps" states that it is not limited to any app. It is useful to create token to allow accessing endpoints to some apps.|
|Endpoint||If token is created to allow some requests, there is possible to set endpoint. For example, when creating token for Data migration, there is endpoint set to migration endpoint.|
|Status||Shows the status of the token - either Expired or Active.|
|Action button||You can delete the token here.|
If token is expired, it is deleted automatically when someone is trying to use it.
Button "Create token" opens token creation form.
- Description: It is optional and doesn't affect token using in any way. It should be set to remember why it was created.
- Endpoint: If nothing is set there token will work on any endpoint
- Checkbox should be checked to allow token be used only once
- Token usage - there token can be limited to be used only in some apps
- Token expiration - It it is chosen to limit token - it can be set to numerous hours, days or months When member logs in new token is created. It has value "LoggedInToken" as description. It is deleted only after logging out. Your current session token is hidden. Logging in from different PC's might result in being some of them listed.
Countly provides inline help for users. In order to enable help mode, toggle Management > Help button. In this mode, hover on the window you want to get help about. Until you toggle the help button again, user interface autorefreshing is disabled.