# Cocos2d-x
TIP
Before you begin, please read Preparation before Data Ingestion
Supports platforms : Android, iOS, Windows, MacOS . and the size is about 6.8 M
Latest version: v2.0.1
Update time: November 23, 2023
Resource download: SDK (opens new window), Source Code (opens new window)
Notice
The current documentation applies to v2.0.0 and later versions. For historical versions, please refer to the Data Ingestion Guide - Cocos2d-x (V1) (opens new window), SDK Download (v1.3.5) (opens new window).
# 1. SDK Integration
- Download and unzip the Cocos2d-x SDK (opens new window) Source Code, Add
ThinkingAnalytics
files into your projectClasses
folder - Add the following configuration to
CMakeLists.txt
list(APPEND GAME_SOURCE
Classes/ThinkingAnalytics/Common/TDJSONObject.cpp
)
list(APPEND GAME_HEADER
Classes/ThinkingAnalytics/Common/TDJSONObject.h
Classes/ThinkingAnalytics/Common/TDAnalytics.h
)
if(ANDROID)
list(APPEND GAME_SOURCE
Classes/ThinkingAnalytics/Android/TDAnalytics.cpp
)
elseif(WINDOWS)
list(APPEND GAME_HEADER
Classes/ThinkingAnalytics/Other/ThinkingSDKObject.h
)
list(APPEND GAME_SOURCE
Classes/ThinkingAnalytics/Other/TDAnalytics.cpp
)
elseif(MACOSX)
list(APPEND GAME_HEADER
Classes/ThinkingAnalytics/Other/ThinkingSDKObject.h
)
list(APPEND GAME_SOURCE
Classes/ThinkingAnalytics/Other/TDAnalytics.cpp
)
- Configuration for Android
- Add the
libs
folder to your project directory inproj.android
, and add TDAnalytics.aar、TDCore.aar、TDThirdparty.aar into thelibs
folder - Add the following configuration to
build.gradle
in your project directory inproj.android
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
}
- Configuration for iOS
Use XCode to open the iOS project, Add the
iOS
folder ofThinkingAnalytics
into theClasses/ThinkingAnalytics
directory
In Xcode, go to Targets > Build Setting , add line
-all_load
toOther linker flags
:
- In Xcode, go to Targets > Build Phases > Compile Sources , add configuration
-fobjc-arc
to TDAnalytics.mm file
# 2. Initialization
#include "./ThinkingAnalytics/Common/TDAnalytics.h"
using namespace thinkingdata::analytics;
//Initialize SDK in the main thread
//Method 1
TDAnalytics::init(TE_APP_ID, TE_SERVER_URL);
//Method 2
TDConfig config(TE_APP_ID, TE_SERVER_URL);
TDAnalytics::init(config);
Instruction on parameters:
APPID
: The APPID of your project, which can be found on the project management page of TE.SERVER_URL
:- If you are using a SaaS version, please check the receiver URL on this page
- If you use the private deployment version, you can customize the data tracking URL .
Since Android 9.0+ restricts HTTP requests by default, please use HTTPS protocol only.
# 3. Common Features
We suggested that you read User Identification Rules before using common features; SDK would generate a random number that would be used as the distinct ID, and save the ID locally. Before the user logs in, the distinct ID would be used as the identification ID. Note: The distinct ID would change after the user reinstalled the App or used the APP with a new device.
# 3.1 Login
When the users log in , Login
could be called to set the account ID of the user. TE would use the account ID as the identification ID, and this ID would be saved before Logout
is called. The previous account ID would be replaced if Login
has been called multiple times.
// The login unique identifier of the user, corresponding to the #account_id in data tracking. #Account_id now is TE
TDAnalytics::login("TE");
Login events wouldn't be uploaded in this method.
# 3.2 Super Properties
Super Properties refer to properties that each event might have. You can call setSuperProperties
to set Super Properties. It is recommended that you set Super Properties first before sending data. Some important properties (e.g., the membership class of users, source channels, etc.) should be set in each event. At this time, you can set these properties as Super Properties.
TDJSONObject superProperties;
superProperties.setString("channel", "TE");//string
superProperties.setNumber("age",1);//number
superProperties.setBool("isSuccess",true);//boolean
superProperties.setDateTime("birthday","2020-01-02 10:52:52.290");//time
TDJSONObject object;
object.setString("key", "value");
superProperties.setJsonObject("object", object);// object
TDJSONObject object1;
object1.setString("key", "value");
vector<TDJSONObject> arr;
arr.push_back(object1);
superProperties.setList("object_arr", arr); // array object
vector<string> arr1;
arr1.push_back("value");
superProperties.setList("arr",arr1);//array
TDAnalytics::setSuperProperties(superProperties);
Super Properties would be saved in local storage, and will not need to be called every time the App is opened. If the Super Properties set previously are uploaded after calling setSuperProperties
, previous properties would be replaced.
- The event property is of type
TDJSONObject
. - Key is the name of the property and refers to the string type. It must start with a character, and contain numbers, characters (insensitive to case, and upper cases would be transformed into lower cases by TE) and underscores "_", with a maximum length of 50 characters.
- Value, the value of the property, supports string, numbers, Boolean, time, object, array object, and array
The requirements for event properties and user properties are the same with that for Super Properties
# 3.3 Automatically Track Events
The following code is an example of tracking installation, open_app and close_app events. To get more information about the automatic tracking of SDK, please refer to the Detailed introduction of automatic tracking function
TDAnalytics::enableAutoTrack();
# 3.4 Sending Events
You can call Track
to upload events. It is suggested that you set event properties based on the data tracking plan drafted previously. Here is an example of a user buying an item:
TDJSONObject eventProperties;
eventProperties.setString("product_name", "product name");
TDAnalytics::track("product_buy",eventProperties);
The event name is string type. It could only start with a character and could contain figures, characters, and an underline "_", with a maximum length of 50 characters.
# 3.5 User Properties
You can set general user properties by calling userSet
API. The original properties would be replaced by the properties uploaded via this API. The data type of newly-created user properties must be the same as the uploaded properties. User name setting is taken as the example here:
//the username now is TA
TDJSONObject properties;
properties.setString("username", "TA");
TDAnalytics::userSet(properties);
//the username now is TE
TDJSONObject newProperties;
newProperties.setString("username", "TE");
TDAnalytics::userSet(newProperties);
# 4. Best Practice
The following sample code covers all the above-mentioned operations. It is recommended that the SDK be used in the following steps:
#include "./ThinkingAnalytics/Common/TDAnalytics.h"
using namespace thinkingdata::analytics;
if (privacy policy is authorized) {
TDAnalytics::init(TE_APP_ID, TE_SERVER_URL);
//if the user has logged in, the account ID of the user could be set as the unique identifier
TDAnalytics::login("TE");
//After setting super properties, each event would have super properties
TDJSONObject superProperties;
superProperties.setString("channel", "TE");//string
superProperties.setNumber("age",1);//number
superProperties.setBool("isSuccess",true);//boolean
superProperties.setDateTime("birthday","2020-01-02 10:52:52.290");//time
TDJSONObject object;
object.setString("key", "value");
superProperties.setJsonObject("object", object);// object
TDJSONObject object1;
object1.setString("key", "value");
vector<TDJSONObject> arr;
arr.push_back(object1);
superProperties.setList("object_arr", arr); // array object
vector<string> arr1;
arr1.push_back("value");
superProperties.setList("arr",arr1);//array
//set super properties
TDAnalytics::setSuperProperties(superProperties);
//Enable auto-tracking
TDAnalytics::enableAutoTrack();
//upload events
TDJSONObject eventProperties;
eventProperties.setString("product_name", "product name");
TDAnalytics::track("product_buy",eventProperties);
//Set user properties
TDJSONObject userProperties;
userProperties.setString("username", "TE");
TDAnalytics::userSet(userProperties);
}