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 "/proj.android/src/org/countly “ folder to “/path/to/your_project/proj.android/src/org" folder
- Add following source files’ path to your project’s Android.mk
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 \ ../../Classes/CountlySDK/CountlyiOS/CountlyCplus/ThirdPartyLibs/Sqlite/sqlite3.c LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../Classes 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 https://try.count.ly 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. Countly::sharedInstance()->recordEvent("purchase", 1);
2. Event key, count and sum
Countly::sharedInstance()->recordEvent("purchase", 0.99); // Default Count is 1. Countly::sharedInstance()->recordEvent("purchase", 0.99, 1);
3. Event key and count with segmentation(s)
Map<std::string, __String*> segmentation; segmentation.insert("country", __String::create("Germany")); segmentation.insert("app_version", __String::create("1.0")); 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; segmentation.insert("country", __String::create("Germany")); segmentation.insert("app_version", __String::create("1.0")); 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("firstname.lastname@example.org")); 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("http://example.com/photo.png")); 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:
|name||String||User's full name|
|String||User's email address|
|organization||String||User's organization name|
|phone||String||User's phone number|
|picture||String||URL to avatar or profile picture of the user|
|picturePath||String||Local path to user's avatar or profile picture|
|gender||String||User's gender as M for male and F for female|
|byear||String||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:
- Acquiring a certificate file from Apple
- Setting up application in Countly dashboard
- Integrating Countly Push into iOS app
- Extra features
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/proj.android/src/org/messaging" folder to "/path/to/your_project/proj.android/org"
- 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"> <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" /> <activity android:name="org.messaging.countly.sdk.ProxyActivity" android:label="@string/app_name" android:noHistory="true" android:theme="@android:style/Theme.Translucent" /> <receiver android:name="org.messaging.countly.sdk.CountlyMessaging" android:permission="com.google.android.c2dm.permission.SEND" > <intent-filter> <action android:name="com.google.android.c2dm.intent.RECEIVE" /> <category android:name="ly.count.android.api" /> </intent-filter> </receiver> <service android:name="org.messaging.countly.sdk.CountlyMessagingService" > <meta-data android:name="broadcast_action" android:value="ly.count.android.api.broadcast" /> </service> </application> <permission android:name="com.count.ly.permission.C2D_MESSAGE" android:protectionLevel="signature" /> <uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" /> <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.