Countly Documentation

Countly Resources

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


Countly SDK includes necessary tools to track your application. In order to integrate SDK to your application, follow these steps.

For both platfforms (iOS & Android), download Countly Cocos2dx SDK. Then copy "/Classes/CountlySDK “ folder to “/path/to/your_project/Classes/“ folder.

Cocos2d-x SDK integration for iOS

  • Add “CountlySDK/CountlyiOS” folder in your Xcode project Classes
  • Select your project in the Project Navigator & select the Build Phases tab
  • Open Link Binaries With Libraries expander
  • Click the + button & select CoreTelephony.framework, select Optional (instead of Required)
  • (optional) Drag and drop the added framework to the Frameworks group

Cocos2d-x SDK integration for Android

  • Copy "/ “ folder to “/path/to/your_project/" folder
  • Add following source files’ path to your project’s

LOCAL_SRC_FILES := hellocpp/main.cpp \
../../Classes/CountlySDK/CountlyiOS/CountlyCplus/Countly.cpp \ ../../Classes/CountlySDK/CountlyAndroid/CountlyDeviceInfo.cpp \
../../Classes/CountlySDK/CountlyAndroid/CountlyCrashDetail.cpp \
../../Classes/CountlySDK/CountlyiOS/CountlyCplus/CountlyEvent.cpp \
../../Classes/CountlySDK/CountlyiOS/CountlyCplus/CountlyUtils.cpp \
../../Classes/CountlySDK/CountlyAndroid/CountlyExceptionHandler.cpp \
../../Classes/CountlySDK/CountlyiOS/CountlyCplus/CountlyBackTrace.cpp \
../../Classes/CountlySDK/CountlyiOS/CountlyCplus/CountlyDBManager.cpp \
../../Classes/CountlySDK/CountlyiOS/CountlyCplus/CountlyEventQueue.cpp \
../../Classes/CountlySDK/CountlyiOS/CountlyCplus/CountlyConnection.cpp \
../../Classes/CountlySDK/CountlyiOS/CountlyCplus/CountlyUserDetails.cpp \
../../Classes/CountlySDK/CountlyiOS/CountlyCplus/CountlyDeviceInfoModel.cpp \
../../Classes/CountlySDK/CountlyiOS/CountlyCplus/CountlyConnectionQueue.cpp \
LOCAL_C_INCLUDES += $(LOCAL_PATH)/../../Classes/CountlySDK/CountlyAndroid
LOCAL_C_INCLUDES += $(LOCAL_PATH)/../../Classes/CountlySDK/CountlyiOS/CountlyCplus


In your AppDelegate.cpp, #include Countly.h
and inside bool AppDelegate::applicationDidFinishLaunching() add following line:
Countly::sharedInstance()->startOnCloudWithAppKey("YOUR_APP_KEY ", “https://YOUR_API_HOST");

You can get “YOUR_APP_KEY” from County Server. Make sure you use App Key (found under Management -> Applications) and not API Key or App ID. Entering API Key or App ID will not work.

YOUR_API_HOST is the server name that you are going to send data to. This will be if you use Enterprise Edition trial servers, or your server IP if you have installed Countly on your own servers.

Setting up custom events

In all the examples below, we will be recording a purchase event. Here is a quick summary of what information each usage will provide us:

  • Usage 1: how many times purchase event occurred.
  • Usage 2: how many times purchase event occurred + the total amount of those purchases.
  • Usage 3: how many times purchase event occurred + which countries & application versions those purchases were made from.
  • Usage 4: how many times purchase event occurred + the total amount, both of which are also available segmented into countries and application versions.

1. Event key and count

Countly::sharedInstance()->recordEvent("purchase");  // Default Count is 1.

2. Event key, count and sum

Countly::sharedInstance()->recordEvent("purchase", 0.99);  // Default Count is 1.
Countly::sharedInstance()->recordEvent("purchase", 0.991);

3. Event key and count with segmentation(s)

Map<std::string__String*> segmentation;
Countly::sharedInstance()->recordEvent("purchase"segmentation);  // Default Count is 1.
Countly::sharedInstance()->recordEvent("purchase"segmentation, 1);

4. Event key, count and sum with segmentation(s)

Map<std::string__String*> segmentation;
Countly::sharedInstance()->recordEvent("purchase", segmentation, 0.99);  // Default Count is 1.
Countly::sharedInstance()->recordEvent("purchase", segmentation, 0.99, 1);

Keep in mind that there is no limit on number of segmentation key/value pairs to use. So, you can extend the above examples and use country, app_version, game_level, time_of_day and any other segmentation that will provide you valuable insights.

Setting up crash reports

Cocos2dx SDK can be used for Countly Crash Reporting service in addition to Countly Analytics. If the only thing you need is Countly Analytics, you can skip this section. 
For Countly Crash Reporting, you will have to add one more line of Countly code to your application. Inside AppDelegate::applicationDidFinishLaunching()method, just after the line you started Countly, add this line:


The following function enables crash reporting, that will automatically catch uncaught java, objective-c and c++ exceptions.

Adding a custom key-value segment to crash report

You can enable crash reporting with a key/value segments to crash report. For example, which specific library or framework version you used in your app, so you can figure out if there is any correlation between specific library or other segment and crash reports. Use following function for this purpose:

Countly::sharedInstance()->startCrashReportingWithSegments(Map<string, __String*> segments)

With this code, Countly Cocos2dx SDK will generate a crash report if your application crashes due to an exception and sends it to Countly Server for further inspection. If a crash report can not be delivered to server (i.e. no internet connection, unavailable server), SDK stores the crash report locally in order to try it again later.

Information sent to Countly servers

For Cocos2dx, a crash report includes following information in addition to Countly Analytics already provides:

  • Exception Name
  • Exception Description
  • Stack Trace
  • Used RAM
  • Total RAM
  • Used Disk
  • Total Disk
  • Battery Level
  • Device Orientation
  • Connection Type
  • OpenGL ES Version
  • JailBrake State
  • Background State
  • Time Since Launch

Setting up User Profiles

This feature is available with Enterprise Edition subscription.

You can see detailed user information on your Countly Analytics dashboard by recording user details with following method (with user data and custom map):

Map<std::string, __String*> data;
  data.insert(kCLYUserName, __String::create("John Doe"));
  data.insert(kCLYUserUsername, __String::create("John"));
  data.insert(kCLYUserEmail, __String::create(""));
  data.insert(kCLYUserOrganization, __String::create("United Nations"));
  data.insert(kCLYUserPhone, __String::create("+1234567890"));
  data.insert(kCLYUserGender, __String::create("M"));
  data.insert(kCLYUserPicturePath, __String::create("photo.png "));
  data.insert(kCLYUserPicturePath, __String::create(""));
  data.insert(kCLYUserBirthYear, __String::create("1970"));
  Map<std::string, __String*> custom;
  custom.insert("key1", __String::create("Value1"));
  custom.insert("key2", __String::create("Value2"));
  Countly::sharedInstance()->recordUserDetails(data, custom);

Possible keys for user data are:




User's full name



User's nickname



User's email address



User's organization name



User's phone number



URL to avatar or profile picture of the user



Local path to user's avatar or profile picture



User's gender as M for male and F for female



User's year of birth as integer

Note 1. Using "" for strings or negative number for year will effectively delete property.

Note 2. For custom user properties, you may use any key values to be stored and displayed on your Countly backend.

Note 3. Keys with . or $ symbols will have those symbols removed.

Setting up push notifications for iOS

We can say that setting up push notifications under Cocos2d-x is very similar to setting up push notifications for iOS, depicted under iOS SDK documentation. For this reason, follow those steps:

For 3rd step (Integrating Countly Push into iOS app), use "#include "CountlyMessaging.h" instead of "#import "Countly.h".

Setting up push notifications for Android

  • Copy “src/" folder to "/path/to/your_project/"
  • Modify "Cocos2dxActivity" to "GPCocos2dxActivity" in your project MainActivity (AppActivity) class
  • Edit AndroidManifest.xml as follows:
<application android:label="@string/app_name" android:icon="@drawable/icon">
            android:value="@integer/google_play_services_version" />
            android:theme="@android:style/Theme.Translucent" />
            android:permission="" >
                <action android:name="" />
                <category android:name="" />
<service android:name="org.messaging.countly.sdk.CountlyMessagingService" >
                android:value="" />
    <permission android:name=""
        android:protectionLevel="signature" />
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="" />
    <uses-permission android:name="android.permission.GET_ACCOUNTS" /><uses-permission android:name="android.permission.WAKE_LOCK" />

After this point, refer to Countly Android SDK documentation step by step for following chapters:

Now we'll integrate Countly push features inside your Android application. For this, in your MainActivity (AppActivity) and inside protected void onCreate(Bundle savedInstanceState),
add the line CountlyMessaging.init(this, AppActivity.class, PROJECT_NUMBER, null);,
where PROJECT_NUMBER is Project Number you get from Google Developers Console.

Now, go back to Android push notification document and read the following for automatic message handling and Testing.