Cocos2d-x

提示

在接入前, 请先阅读接入前准备。

Cocos2d-x SDK 支持在iOS、Android、Mac、Windows平台运行，大小约为 6.8M

最新版本: v2.0.1

更新时间: 2023-11-23

资源下载:源码 (opens new window)、SDK下载 (opens new window)

注意

当前文档适用于 v2.0.0 及以后的版本，历史版本请参考 Cocos2d-x 接入指南（V1） (opens new window)，SDK下载（v1.3.5） (opens new window)

一、集成SDK

1. 下载 Cocos2d-x SDK (opens new window) 资源文件，解压文件，把 ThinkingAnalytics 文件夹放入 Classes 文件夹
2. 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
        )

1. 添加 Android 端配置

• 在 proj.android 中的 app 目录下添加 libs 文件夹，把 TDAnalytics.aar、TDCore.aar、TDThirdparty.aar 拷贝到 libs 文件夹
• 在 proj.android 中的 app/src 目录下逐级添加 cn/thinkingdata/analytics 文件夹，把 TDAnalyticsCocosAPI.java 拷贝到 cn/thinkingdata/analytics 文件夹
• proj.android中app 目录下的 build.gradle 添加如下配置

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
}

1. 添加 iOS 端配置

• 使用 Xcode 打开 iOS 项目，直接拖拽 ThinkingAnalytics 下面的 iOS 文件夹放入 Classes/ThinkingAnalytics 目录下
  

• Build Setting -> Other Linker Flags 中的添加 -ObjC
  

• Build Phases -> Compile Sources 中的 TDAnalytics.mm 添加 -fobjc-arc
  

• 在 Build Setting - Header Search Paths 中添加

"$(SRCROOT)/../Classes/ThinkingAnalytics/iOS/ThinkingSDK.framework/Headers"

• 在 Build Setting - Framework Search Paths 中添加

"$(SRCROOT)/../Classes/ThinkingAnalytics/iOS"

• Build Phases - Link Binary With Libraries

WebKit.framework, GameController.framework, MediaPlayer.framework

二、初始化

#include "./ThinkingAnalytics/Common/TDAnalytics.h"
using namespace thinkingdata::analytics;
// 在主线程中初始化 SDK 
//方式一
TDAnalytics::init(TA_APP_ID, TA_SERVER_URL);
//方式二
TDConfig config(TA_APP_ID, TA_SERVER_URL);
TDAnalytics::init(config);

参数说明:

• APPID: 是您的项目的 APPID，可通过在 TA 后台项目管理页面获取
• SERVER_URL: 为数据上传的 URL
  • 如果您对接的是云服务，填入: https://global-receiver-ta.thinkingdata.cn
  • 如果您使用私有化部署版本，请为数据采集地址绑定域名，并配置 HTTPS 证书：https://数据采集地址绑定域名

由于 Android 9.0+ 默认限制 HTTP 请求，因此请务必使用 HTTPS 协议

三、常用功能

在使用常用功能之前，建议你先了解用户识别规则；SDK 默认会生成随机数作为访客ID，并持久化存储访客ID在本地；用户未登录之前，会以访客ID作为身份识别ID。注意:访客 ID 在用户重新安装 App 以及更换设备时将会变更。

3.1 设置账号ID

在用户进行登录时，可调用 Login 来设置用户的账号 ID， TA 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 Logout 之前一直保留。多次调用 Login 将覆盖先前的账号 ID 。

// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
TDAnalytics::login("TA");

Login 可以多次调用，每次调用会判断传入的账号 ID 与先前保存的 ID 是否一致，一致则忽略调用，不一致则会覆盖先前的 ID。

该方法不会上传登录事件

3.2 设置公共事件属性

公共事件属性指的就是每个事件都会带有的属性，您可以调用 setSuperProperties 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。对于一些重要的属性，譬如用户的会员等级、来源渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。

TDJSONObject superProperties;
superProperties.setString("channel", "ta");//字符串
superProperties.setNumber("age",1);//数字
superProperties.setBool("isSuccess",true);//布尔
superProperties.setDateTime("birthday","2020-01-02 10:52:52.290");//时间

TDJSONObject object;
object.setString("key", "value");
superProperties.setJsonObject("object", object);// 对象

TDJSONObject object1;
object1.setString("key", "value");
vector<TDJSONObject> arr;  
arr.push_back(object1);
superProperties.setList("object_arr", arr); // 对象组

vector<string> arr1;
arr1.push_back("value");
superProperties.setList("arr",arr1);//数组

TDAnalytics::setSuperProperties(superProperties);

公共事件属性将会被保存到缓存中，无需每次启动 App 时调用。如果调用 setSuperProperties 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。

• 事件属性是 TDJSONObject 类型，其中每个元素代表一个属性
• Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,TA会统一转化为小写字母
• Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组

事件属性、用户属性的要求与公共事件属性保持一致

3.3 开启自动采集

以下代码示例开启安装、启动、关闭事件，如果您想详细了解SDK的自动采集能力，可以查看自动采集功能详细介绍

// 开启自动采集
TDAnalytics::enableAutoTrack();

3.4 发送事件

您可以调用 Track 来上传事件，建议您根据先前梳理的埋点文档来设置事件的属性以及发送信息的条件，此处以用户购买某商品作为范例：

TDJSONObject eventProperties;
eventProperties.setString("product_name", "商品名");
TDAnalytics::track("product_buy", eventProperties);

事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。

3.5 设置用户属性

对于一般的用户属性，您可以调用 userSet 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

//此时username为TA
TDJSONObject properties;
properties.setString("username", "TA");
TDAnalytics::userSet(properties);
//此时userName为TE
TDJSONObject newProperties;
newProperties.setString("username", "TE");
TDAnalytics::userSet(newProperties);

属性格式要求与事件属性保持一致。

四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

#include "./ThinkingAnalytics/Common/TDAnalytics.h"
using namespace thinkingdata::analytics;

if (授权隐私政策) {
      //初始化SDK
      TDAnalytics::init(TA_APP_ID, TA_SERVER_URL);
      //如果用户已登录，可以设置用户的账号ID作为身份唯一标识
      TDAnalytics::login("TA");
      
      //设置公共事件属性以后，每个事件都会带有公共事件属性
      TDJSONObject superProperties;
      superProperties.setString("channel", "ta");//字符串
      superProperties.setNumber("age",1);//数字
      superProperties.setBool("isSuccess",true);//布尔
      superProperties.setDateTime("birthday","2020-01-02 10:52:52.290");//时间

      TDJSONObject object;
      object.setString("key", "value");
      superProperties.setJsonObject("object", object);// 对象

      TDJSONObject object1;
      object1.setString("key", "value");
      vector<TDJSONObject> arr;  
      arr.push_back(object1);
      superProperties.setList("object_arr", arr); // 对象组

      vector<string> arr1;
      arr1.push_back("value");
      superProperties.setList("arr",arr1);//数组
      TDAnalytics::setSuperProperties(superProperties);
      
      //开启自动采集事件
      TDAnalytics::enableAutoTrack();
      
      //发送事件
      TDJSONObject eventProperties;
      eventProperties.setString("product_name", "商品名");
      TDAnalytics::track("product_buy",eventProperties);
      
      //设置用户属性
      TDJSONObject userProperties;
      userProperties.setString("username", "TE");
      TDAnalytics::userSet(userProperties);
}