Countly Documentation

Countly Resources

Here you'll find comprehensive guides to help you start working with Countly as quickly as possible.

Introduction to Countly

This document is an introduction to Countly main dashboard and gives an overview of user interface components for mobile and web analytics.

Changelog

  • 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

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:

  1. Choose your Linux edition (e.g Countly Community Edition or Enterprise Edition), by looking at comparison table.
  2. Install the server application so it’s ready to collect data or use a preinstalled server.
  3. Implement SDK in your application for mobile analytics.
  4. Put the application in your device and test, or, visit your web application so it starts sending data.
  5. 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:

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.

  1. Navigation bar
  2. Top bar
  3. Real-time panel
  4. Quick date selector
  5. Analytics panel

Note

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.

Navigation bar

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.

Top bar

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.

Real-time panel

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.

Important Note

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.

Analytics panel

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:

  1. Total sessions: Number of times your application is opened. Click this item to see a time series representation of total sessions.
  2. Total users: Number of unique devices your application is used from. Click this item to see a time series representation of total users.
  3. New users: Number of first time users. Click this item to see a time series representation of new users.
  4. Time spent: Total time spent for your application. Click this item to see a time series representation of average time spent per user.
  5. 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.
  6. 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.

For example:

  • 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 only)

Android devices have screen densities and this menu shows densities reported by device. This menu is only for Android applications.

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.

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.

Note

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.

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:

Star rating (mobile)

This plugin shows how many users give which ratings (1 star - 5 star) to your application. When this plugin is viewed (under Engagement > Star Rating), there are two charts shown - cumulative and time series. Cumulative graph shows all star rating numbers, and time series shows all given stars based on the time selected.

In order for this plugin to show data, iOS and Android SDK should be configured so that it shows a popup to end users, and they start sending star rating data to Countly server.

View frequency

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.

4. Events

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.

Configuring events

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.

For more information about how to capture and send events to Countly server, see Custom Events article. For references and hands-on examples, please see SDK methods for custom events.

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.

Managing applications

Applications can be managed by global users (more information later). To add a web, mobile or desktop application, follow the steps below:

  1. Go to Management > Applications
  2. Click “Add”
  3. Enter your application name, type, the time zone you are in, and application icon.
  4. 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.

Managing users

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:

  1. 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.
  2. Admin can manage applications, e.g add an application, edit it or remove it completely from the management dashboard.
  3. 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.

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 "Restrict sections" and you'll see a popup similar to this.

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.

Managing groups

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.

Viewing logs

Countly plugins have the ability to help you view different types of logs. Most important plugins that come with Countly are:

  1. Error logs plugin: Shows errors occurring during system boot or run.
  2. System logs plugin: Shows who has logged in, when was a configuration made and other details.
  3. Event logs plugin: Shows each event, together with when it happened from which device and other details.

Sending email reports periodically

Countly can send email reports to you or your colleagues periodically. In order to do this, go to Management > 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

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.

Why use alerts?

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.

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.

In order to learn more about Alerts, please see Alerts section.

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 Management > Data Populator.

Using plugins

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.

Blocking event and session requests

Sometimes, for different reasons, you may want to block particular event or session data to be written to database. In such cases, Blocking Requests plugin come to rescue.

You can add as many rules as you want, e.g based on IP, country, browser, platform etc.

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

Getting help

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.

Introduction to Countly

This document is an introduction to Countly main dashboard and gives an overview of user interface components for mobile and web analytics.