# Cocos2d-Lua SDK 使用指南

提示

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

您可以在 GitHub (opens new window) 获取 Cocos2d-Lua SDK 源码。

Cocos2d-Lua SDK 支持在 iOS、Android 平台运行，大小约为 7.1M

最新版本为: v1.0.0

更新时间为: 2022-03-28

# 一、初始化 SDK

# 1.1 集成 SDK

添加 Cocos2d-Lua 配置

下载 Cocos2d-Lua SDK (opens new window) 资源文件，解压文件后把 ThinkingAnalyticsSDK.lua 添加到 src 文件夹

添加 Android 配置

在 frameworks/runtime-src/proj.android/app 目录下添加 libs 文件夹，把 ThinkingSDK.aar 添加到 libs 文件夹

在 frameworks/runtime-src/proj.android/app/src/org/cocos2dx/lua 目录下添加 ThinkingAnalyticsProxyJava.java

在 CMakeLists.txt 中加入如下配置

if(ANDROID) list(APPEND GAME_SOURCE # [ThinkingAnalyticsSDK] 添加以下代码 ${RUNTIME_SRC_ROOT}/proj.android/app/src/org/cocos2dx/lua/ThinkingAnalyticsProxyJava.java ${RUNTIME_SRC_ROOT}/proj.android/app/libs/ThinkingSDK.aar endif()

如下图：

在 frameworks/runtime-src/proj.android/app 目录下的 build.gradle 中添加如下配置

dependencies { // 添加 .aar 类型文件的引入 implementation fileTree(include: ['*.jar','*.aar'], dir: 'libs')

添加 iOS 配置（** Cocos2d-Lua-Community 4.x* *）

把 ThinkingAnalyticsProxy.h 、 ThinkingAnalyticsProxy.mm 、 ThinkingSDK.framework 添加到 frameworks/runtime-src/proj.ios_mac/ios 目录

在 CMakeLists.txt 中加入如下配置

if(APPLE) if(IOS) list(APPEND GAME_HEADER # [ThinkingAnalyticsSDK] 添加以下代码 ${RUNTIME_SRC_ROOT}/proj.ios_mac/ios/ThinkingAnalyticsProxy.h list(APPEND GAME_SOURCE # [ThinkingAnalyticsSDK] 添加以下代码 ${RUNTIME_SRC_ROOT}/proj.ios_mac/ios/ThinkingAnalyticsProxy.mm ${RUNTIME_SRC_ROOT}/proj.ios_mac/ios/ThinkingSDK.framework endif() endif() if(IOS) # [ThinkingAnalyticsSDK] 添加以下代码 target_link_libraries(${APP_NAME} ${RUNTIME_SRC_ROOT}/proj.ios_mac/ios/ThinkingSDK.framework) endif() if(IOS) # [ThinkingAnalyticsSDK] 添加以下代码 set(CMAKE_EXE_LINKER_FLAGS -ObjC) endif()

添加 iOS 配置（Cocos2d-Lua-Community 3.x）

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

Build Setting -> Other Linker Flags 中的 Debug 和 Release 分别添加 -force_load "$(SRCROOT)/ThinkingAnalyticsSDK/ThinkingSDK.framework/ThinkingSDK"

# 1.2 初始化 SDK

-- 引入 ThinkingAnalyticsSDK local ThinkingAnalyticsSDK = require("ThinkingAnalyticsSDK") -- 初始化 ThinkingAnalyticsSDK local APP_ID = "YOUR_APP_ID" local SERVER_URL = "YOUR_SERVER_URL" ThinkingAnalyticsSDK.init(APP_ID, SERVER_URL, ThinkingAnalyticsSDK.debugModel.debugOff)

注意：由于一些设备默认禁止明文传输，因此强烈建议您使用 HTTPS 格式的接收端地址。

# 二、设置用户 ID

在使用 Cocos2d-Lua SDK 之后，SDK 默认会使用随机 UUID 作为每个用户的访客 ID，该 ID 将会作为用户在未登录状态下身份识别 ID。需要注意的是，默认访客 ID 在用户重新安装游戏以及更换设备时将会变更。

# 2.1 设置访客 ID（可选）

如果您的游戏对每个用户有自己的访客 ID 管理体系，则您可以调用 identify() 来设置访客 ID:

-- 设置访客 ID ThinkingAnalyticsSDK.identify("LuaDistinctId")

如果需要获得访客 ID，可以调用 getDistinctId() 获取：

-- 获取访客 ID ThinkingAnalyticsSDK.getDistinctId()

# 2.2 设置与清除账号 ID

在用户进行登录时，可调用 login() 来设置用户的账号 ID，在设置完账号 ID 后，将会以账号 ID 作为用户标识 ID，并且设置的账号 ID 将会在调用 logout() 之前一直保留：

-- 设置账号 ID ThinkingAnalyticsSDK.login("LuaAccountId") -- 清除账号 ID ThinkingAnalyticsSDK.logout()

注意：该方法不会上传用户登录、用户登出等事件。

# 三、上传事件

通过 track() 可以上报事件及其属性。一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用 TA 后台，我们推荐您先上传几个关键事件。

我们也支持了若干自动采集事件，包括游戏启动、关闭、安装等事件。

# 3.1 上传事件

建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件。事件名称是 string 类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感。

local properties = { test_string="string", test_number=123.456, test_bool=true, test_date=os.date("%Y-%m-%d %H:%M:%S"), test_list={"a","b","c"}, ThinkingAnalyticsSDK.track("click", properties)

事件属性是 table 类型，其中每个元素代表一个属性；

事件属性 Key 为属性名称，为 string 类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感；

属性值支持六种类型：字符串、数值类、 bool 、 Array 、对象、对象组类型。

复杂数据类型，属性可传入对象和对象组：

-- 自定义事件属性 local properties = { test_string="string", test_number=123.456, test_bool=true, test_date=os.date("%Y-%m-%d %H:%M:%S"), test_list={"a","b","c"}, -- 对象 test_params={test_string="string"}, -- 对象组 test_params_list={ {test_string="string"}, {test_string2="string2"} -- 上报事件 ThinkingAnalyticsSDK.track("crack_muti_property", properties)

# 3.2 设置静态公共属性

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

-- 设置公共属性 ThinkingAnalyticsSDK.setSuperProperties({ channel = "App Store", trip = {"Car", "Train"}

公共事件属性将会被保存到缓存中，无需每次启动 APP 时调用。如果调用 setSuperProperties() 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和 track() 上传的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性。

如果您需要删除某个公共事件属性，可以调用 unsetSuperProperty() 清除其中一个公共事件属性；如果您想要清空所有公共事件属性，则可以调用 clearSuperProperties() ；如果您想要获取所有公共事件属性，可以调用 getSuperProperties() ;

-- 清除属性名为 trip 的公共属性 ThinkingAnalyticsSDK.unsetSuperProperty("trip") -- 清空所有公共属性 ThinkingAnalyticsSDK.clearSuperProperties() -- 获取所有公共属性 ThinkingAnalyticsSDK.currentSuperProperties()

# 3.3 设置动态公共属性

动态公共属性的特性，即公共属性可以上报时获取当时的值，使得诸如会员等级之类的可变公共属性可以被便捷地上报。通过 setDynamicSuperProperties() 设置动态公共属性类之后，SDK 将会在事件上报时自动获取属性，并添加到触发的事件中。以下例子是每次上报时将时间加入到事件中，当事件触发时，就会将 dynamicProperties 的返回值加入到事件属性中。

-- 设置动态公共属性，在事件上报时动态获取事件发生时刻 local dynamicProperties = function() local properties = { today = os.date("%Y-%m-%d") return properties ThinkingAnalyticsSDK.setDynamicSuperProperties(dynamicProperties);

# 3.4 记录事件时长

如果您需要记录某个事件持续时长，您可以调用 timeEvent() 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 #duration 这一属性来表示记录的时长，单位为秒。

-- 调用 TimeEvent 开启对 TimeEvent 事件的计时 ThinkingAnalyticsSDK.timeEvent("TimeEvent") -- do some thing... -- 通过 track() 上传 TimeEvent 事件时，会在属性中添加 #duration 属性 ThinkingAnalyticsSDK.track("TimeEvent", {})

# 四、用户属性

TA 平台目前支持的用户属性设置接口为 userSet() 、 userSetOnce() 、 userAdd() 、 userAppend() 、 userUnset() 、 userDelete() 。

# 4.1 userSet

对于一般的用户属性，您可以调用 userSet() 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性。

-- 设置用户属性 ThinkingAnalyticsSDK.userSet({ name = "Mike", age = 22, isVip = true

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

# 4.2 userSetOnce

如果您要上传的用户属性只要设置一次，则可以调用 userSetOnce() 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息：

-- 设置用户首次属性 ThinkingAnalyticsSDK.userSetOnce({ registTime = os.date("%Y-%m-%d %H:%M:%S")

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

# 4.3 userAdd

当您要上传数值型的属性时，您可以调用 userAdd() 来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值，等同于相减操作。

-- 累加数值型用户属性 ThinkingAnalyticsSDK.userAdd({ age = 1

设置的属性 key 为字符串，Value 只允许为数值。

# 4.4 userAppend

您可以调用 userAppend() 为 Array 类型的用户属性追加元素:

-- 追加列表型用户属性 ThinkingAnalyticsSDK.userAppend({ weapon = {"m41", "bulldog"}

# 4.5 userUnset

如果您需要重置用户的某个属性，可以调用 userUnset() 将该用户指定用户属性的值清空，此接口支持传入字符串类型的参数:

-- 清除指定用户属性 ThinkingAnalyticsSDK.userUnset("age")

传入值为被清空属性的 Key 值。

# 4.6 userDelete

如果您要删除某个用户，可以调用 userDelete() 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

-- 删除用户 ThinkingAnalyticsSDK.userDelete()

# 五、自动采集事件

ThinkingAnalytics SDK 提供了三种事件的自动采集：

appInstall : 游戏安装，当安装后首次打开游戏会采集该事件（事件名 ta_app_install ）

appStart : 游戏进入前台的时候采集该事件（事件名 ta_app_start ）

appEnd : 游戏退到后台的时候采集该事件（事件名 ta_app_end ）

通过调用 enableAutoTrack() 接口可以开启自动采集：

-- 开启自动采集默认false：关闭，true：开启 local autoTack = { appInstall = true, -- 开启自动采集安装事件 appStart = true, -- 开启自动采集开始事件 appEnd = true -- 开启自动采集结束事件 ThinkingAnalyticsSDK.enableAutoTrack(autoTack)

注意：如果您需要自定义访客 ID，请务必在开启自动采集功能之前调用 identify() 接口设置访客 ID.

# 六、其他配置选项

# 6.1 获取设备 ID

SDK 在初始化完成后，会自动生成设备 ID，并记录在本地缓存，对于同一应用或游戏，一台设备的设备 ID 是不变的，可以调用 getDeviceId() 获取设备 ID：

-- 获取设备 ID ThinkingAnalyticsSDK.getDeviceId()

# 6.2 打印上传数据 Log

logLevelNone ：打印日志关闭

logLevelError ：打印错误日志

logLevelInfo ：打印详细日志

logLevelDebug ：打印调试日志

-- 开启打印日志 ThinkingAnalyticsSDK.setLogLevel(ThinkingAnalyticsSDK.logLevel.logLevelDebug)

# 6.3 暂停 / 停止数据上报

暂停 SDK 上报（ enableTracking ）

您可能希望在一些场景下，暂时停止 SDK 的数据采集以及上报，比如用户处于测试环境中、或者用户登录了一个测试账号，此时您可以调用下列接口，暂时停止 SDK 的上报。

您可以通过某一实例（包括主要实例以及轻实例）调用 enableTracking() 接口传入 false ，来暂停 SDK 的上报，该实例已经设置的 #distinct_id 、 #account_id 、公共属性等将保留；该实例已经采集但还未上报成功的数据将继续尝试上报；后续该实例不能采集以及上报任何新数据、不能设置访客 ID、账户 ID 以及公共属性等，但是可以读取该实例已经设置的公共属性和设备 ID、访客 ID、账号 ID 等信息。

实例的停止状态将会被保存在本地缓存，直到调用 enableTracking() 接口传入 ture ，SDK 实例将会重新恢复数据采集以及上报，需要注意轻实例因为不进行缓存，因此每次打开 APP 后，轻实例的暂停状态不会被保留，将重新开启上报。

-- 暂停默认实例的上报，已缓存数据和已经设置的信息不被清除 ThinkingAnalyticsSDK.enableTracking(false) -- 恢复默认实例的上报 ThinkingAnalyticsSDK.enableTracking(true)

停止 SDK 上报（ optOutTracking ）

在一些特殊场景下，您可能需要完全停止 SDK 的功能，比如在适用 GDPR 的地区，用户选择不提供数据采集权限，则您可以调用如下接口完全关闭 SDK 的功能。

optOutTracking() 只能通过主要实例调用，与 enableTracking() 的最大区别在于，其将会清空该实例的本地缓存，包括本实例的访客 ID，账号 ID，公共属性，以及未上报的数据队列。之后再关闭该实例的采集和上报功能。

-- 停止默认实例的上报, 并清空本地缓存 ThinkingAnalyticsSDK.optInTracking(false, false)

如果您希望关闭 SDK 功能的同时，删除该用户在 TA 集群中的用户数据，可以调用 optInTracking() 接口传入两个参数 false 和 true ，这将会在停止 SDK 实例的功能前，上报一条 user_delete 数据，以删除该用户的用户数据。

-- 停止默认实例的上报，并发送 user_del ThinkingAnalyticsSDK.optInTracking(false, true)

实例的停止状态也将保存在本地缓存，直到调用 optInTracking() ，后续可以继续上报，但此时相当于一个全新的实例

-- 重新开启上报 ThinkingAnalyticsSDK.optInTracking(true, false)

# 6.4 SDK 运行模式

SDK 支持在三种模式下运行：

debugOff : 普通模式，数据会存入缓存，并依据一定的缓存策略上报

debugOn : Debug 模式，数据逐条上报。当出现问题时会以日志和异常的方式提示用户

debugOnly : Debug Only 模式，只对数据做校验，不会入库

注意: DEBUG 模式仅仅用于集成阶段数据校验，不要在生产模式下使用。

为了避免 Debug 模式在生产环境上线，规定只有指定的设备才能开启 Debug 模式。只有在客户端开启了 Debug 模式，并且设备 ID 在 TA 后台的"埋点管理"页的"Debug 数据"板块中配置了的设备才能开启 Debug 模式。

设备 ID 可以通过以下三种方式获取：

TA 平台中事件数据中的 #device_id 属性

客户端日志：SDK 初始化完成后会打印设备 ID

通过实例接口调用：获取设备 ID

# 七、相关预置属性

# 7.1 预置属性说明

各个平台采集的预制属性会有一定的差异，具体可以参考如下文档: Android 平台、 iOS 平台

# 7.2 获取预置属性

服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取 App 端的预置属性，再传给服务端。

-- 获取属性对象 local presetProperties = ThinkingAnalyticsSDK.getPresetProperties() -- 生成事件预置属性 local properties = presetProperties.toEventPresetProperties() "#carrier": "中国电信", "#os": "Android", "#device_id": "abb8e87bfb5ce66c", "#screen_height": 2264, "#bundle_id": "com.sw.thinkingdatademo", "#manufacturer": "realme", "#device_model": "RMX1991", "#screen_width": 1080, "#system_language": "zh", "#os_version": "10", "#network_type": "WIFI", "#zone_offset": 8， "#app_version":"1.0" ]]-- -- 获取某个预置属性 local bundleId = presetProperties.bundleId -- 包名 local mOS = presetProperties.os -- 系统类型，如 Android/iOS local systemLanguage = presetProperties.systemLanguage -- 手机系统语言类型 local screenWidth = presetProperties.screenWidth -- 屏幕宽度 local screenHeight = presetProperties.screenHeight -- 屏幕高度 local deviceModel = presetProperties.deviceModel -- 设备型号 local deviceId = presetProperties.deviceId -- 设备唯一标识 local carrier = presetProperties.carrier -- 手机SIM卡运营商信息，双卡双待时，取主卡的运营商信息 local manufacture = presetProperties.manufacturer -- 手机制造商如 HuaWei local networkType = presetProperties.networkType -- 网络类型 local osVersion = presetProperties.osVersion -- 系统版本号 local appVersion = presetProperties.appVersion -- app版本号 local zoneOffset = presetProperties.zoneOffset -- 时区偏移值

IP，国家城市信息由服务端解析生成，客户端不提供接口获取这些属性

# 八、进阶功能

Cocos2d-Lua SDK 支持上报三种特殊类型事件: 首次事件、可更新事件、可重写事件。

# 8.1 首次事件

首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上第一次发生的事件，则可以用首次事件来上报数据。

-- 示例：上报设备首次事件, 假设事件名为 DEVICE_FIRST ThinkingAnalyticsSDK.trackFirst("DEVICE_FIRST", nil, { test_string="first_string"

如果您希望以设备以外的其他维度来判断是否首次，则可以为首次事件设置 FIRST_CHECK_ID。例如您需要记录某个账号的首次事件，可以将账号 ID 设置为首次事件的 FIRST_CHECK_ID:

-- 示例：上报用户账号的首次事件, 假设事件名为 DEVICE_FIRST ThinkingAnalyticsSDK.trackFirst("DEVICE_FIRST", "First_EventId", { test_string="first_string"

注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 1 小时入库。

# 8.2 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

-- 示例：上报可被更新的事件，假设事件名为 UPDATABLE_EVENT -- 上报后事件属性 status 为 3, price 为 100 ThinkingAnalyticsSDK.trackUpdate("UPDATABLE_EVENT", "Update_EventId", { status = 3, price = 100 -- 上报后事件属性 status 被更新为 5, price 不变 ThinkingAnalyticsSDK.trackUpdate("UPDATABLE_EVENT", "Update_EventId", { status = 5

# 8.3 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

-- 示例：上报可被重写的事件，假设事件名为 OVERWRITABLE_EVENT ThinkingAnalyticsSDK.trackOverwrite("OVERWRITABLE_EVENT", "Overwrite_EventId", { status = 3, price = 100 -- 上报后事件属性 status 被更新为 5, price 属性被删除 ThinkingAnalyticsSDK.trackOverwrite("OVERWRITABLE_EVENT", "Overwrite_EventId", { status = 5

# ChangeLog

# v1.0.0 2022/03/28

支持访客 ID 和用户账号的设置

支持事件和用户属性上报

支持启动 / 关闭 / 安装事件的自动上报

支持公共属性接口

支持 timeEvent 接口

Cocos2d-x SDK 使用指南 CocosCreator SDK 使用指南