进阶指南
一、设置用户ID
SDK 实例默认会使用随机数作为每个用户的默认访客 ID，该 ID 将会作为用户在未登录状态下身份识别 ID。需要注意的是，访客 ID 在用户清理缓存以及更换设备时将会变更。
1.1 设置访客 ID
一般情况下，您不需要自定义访客 ID. 请确保已经理解用户识别规则，再进行访客 ID 的设置。
如果您的 App 对每个用户有自己的访客 ID 管理体系，则您可以调用 setDistinctId 来设置访客 ID：
// 将访客ID设置为Thinker
TDAnalytics.setDistinctId("Thinker");
如果需要获得当前访客 ID，可以调用 getDistinctId 获取：
//返回访客ID
let distinctId = TDAnalytics.getDistinctId();
如果需要进行设置，必须在初始化之前调用本接口
1.2 设置账号 ID
在用户产生登录行为时，可调用 login 来设置用户的账号 ID。AE 平台优先以账号 ID 作为身份标识，设置后的账号 ID 将会被保存，多次调用 login 将会覆盖先前的账号 ID：
//用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
TDAnalytics.login("TA");
请注意，该方法不会上传用户登录的事件
1.3 清除账号ID
在用户产生登出行为之后，可调用 logout 来清除账号 ID，在下次调用 login 之前，将会以访客 ID 作为身份识别 ID：
// 去除上报数据里的 "#account_id"，之后的数据将不带有 "#account_id"
TDAnalytics.logout();
请注意，该方法不会上传用户登出的事件
二 、发送事件
2.1 普通事件
您可以直接调用 track 上传自定义事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：
TDAnalytics.track({
eventName: "product_buy", // 事件名称
properties: {
product_name: "商品名"
} //事件属性
});
track接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性- 事件的名称是字符串，只能以字母开头，可包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。
- 事件的属性是 JS 对象，每个元素代表一个属性。
- 元素的 name 对应属性的名称，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。
- 元素的Value 为该属性的值，支持
String、Number、Boolean、Date、Object和Array;Object中的内容可以为String、Number、Boolean、Date，Array（内容为字符串);Array中的内容可以为Object和String
2.2 首次事件
首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上第一次发生的事件，则可以用首次事件来上报数据。
TDAnalytics.trackFirst({
eventName: "device_activation",
properties: { key: "value" }
});
如果您希望以设备以外的其他维度来判断是否首次，则可以为首次事件设置 first_check_id. 例如您需要记录某个账号的首次事件，可以将账号 ID 设置为首次事件的 first_check_id:
// 将用户ID设置为首次事件的first_check_id，实现用户首次激活事件的采集
TDAnalytics.trackFirst({
eventName: "account_activation",
firstCheckId: "TA",
properties: { key: "value" }
});
注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 1 小时入库。
2.3 可更新事件
您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。
// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
// 上报后事件属性 status 为 3, price 为 100
TDAnalytics.trackUpdate({
eventName: "UPDATABLE_EVENT",
properties: { status: 3, price: 100 },
eventId: "test_event_id"
});
// 上报后事件属性 status 被更新为 5, price 不变
TDAnalytics.trackUpdate({
eventName: "UPDATABLE_EVENT",
properties: { status: 5 },
eventId: "test_event_id"
});
2.4 可重写事件
可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。
// 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
// 上报后事件属性 status 为 3, price 为 100
TDAnalytics.trackOverwrite({
eventName: "OVERWRITE_EVENT",
properties: { status: 3, price: 100 },
eventId: "test_event_id"
});
// 上报后事件属性 status 被更新为 5, price 属性被删除
TDAnalytics.trackOverwrite({
eventName: "OVERWRITE_EVENT",
properties: { status: 5 },
eventId: "test_event_id"
});
2.5 公共事件属性
对于一些重要的属性，譬如用户的设备 ID、来源渠道、用户状态等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共属性，即每个事件中都带有的属性。我们推荐您在发送事件前，先设置公共属性。
公共属性包含两种，事件公共属性和动态公共属性。在事件上报时，公共属性将会被插入到数据的 properties 中。如果此时公共属性与事件中设置的自定义属性有相同 key 值，则属性会根据下述优先级判断该取什么值：自定义属性>动态公共事件属性>静态公共事件属性>预置属性
2.5.1 静态公共事件属性
事件公共属性指的是静态的公共属性，在设置时只能传入常量，适合设置稳定不变的属性，您可以调用 setSuperProperties 来设置公共事件属性，公共事件属性的格式要求与事件属性一致。
根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。
// 设置公共事件属性，所有数据事件中都会带有这些属性
TDAnalytics.setSuperProperties({
channel: "渠道名",
user_name: "用户名"
});
如果多次调用 setSuperProperties 设置公共事件属性，则同名字段后面的调用会覆盖之前的，不同名字段则会保留。
如果您需要删除某个公共事件属性，可以调用 unsetSuperProperty() 清除其中一个公共事件属性；如果您想要清空所有公共事件属性，则可以调用 clearSuperProperties();如果您想要获取所有公共事件属性，可以调用getSuperProperties;
// 获取静态公共事件属性
var superProperties = TDAnalytics.getSuperProperties();
// 清除一条静态公共事件属性，比如将之前设置 'channel' 属性清除，之后的数据将不会该属性
TDAnalytics.unsetSuperProperty("channel");
// 清除所有静态公共事件属性
TDAnalytics.clearSuperProperties();
2.5.2 动态公共事件属性
动态公共属性会在事件上报时，执行一个 function ，并把返回值作为该动态公共属性的值，加入到事件中。您可以调用 setDynamicSuperProperties 接口设置动态公共属性。该接口接受一个 function 作为参数。
// 通过动态公共属性设置 UTC 时间作为事件属性上报
TDAnalytics.setDynamicSuperProperties(() => {
var localDate = new Date();
return {
utcTime: new Date(
localDate.getTime() + localDate.getTimezoneOffset() * 60000
)
};
});
function 必须返回一个 JS 对象，其中每个元素代表一个属性。 属性格式要求与事件属性一致。
2.6 记录事件时长
您可以调用 timeEvent 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 #duration 这一属性来表示记录的时长，单位为秒。
//以下示例，完成用户在某个商品页面停留时长的统计
TDAnalytics.timeEvent({
eventName: "stay_shop"
});
/**do someting
.......
**/
//用户离开商品页面，计时结束，"stay_shop" 这一事件中将会带有表示事件时长的属性#duration
TDAnalytics.track({
eventName: "stay_shop",
properties: {
product_name: "商品名"
}
});
三、用户属性
3.1 userSet
对于一般的用户属性，您可以调用 userSet 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性
// username为TA
TDAnalytics.userSet({
properties: {
username: "TA"
}
});
//username为AE
TDAnalytics.userSet({
properties: {
username: "AE"
}
});
属性格式要求与事件属性保持一致。
3.2 userSetOnce
如果您要上传的用户属性只要设置一次，则可以调用 userSetOnce 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
//first_payment_time为2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
properties: {
first_payment_time: "2018-01-01 01:23:45.678"
}
});
//first_payment_time仍然为2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
properties: {
first_payment_time: "2018-12-31 01:23:45.678"
}
});
属性格式要求与事件属性保持一致。
3.3 userAdd
当您要上传数值型的属性时，您可以调用 userAdd 来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算
//此时total_revenue为30
TDAnalytics.userAdd({
properties: {
total_revenue: 30
}
});
//此时total_revenue为678
TDAnalytics.userAdd({
properties: {
total_revenue: 648
}
});
设置的属性key为字符串，Value 只允许为数值。
3.4 userUnset
当您要清空用户的某个用户属性值时，您可以调用 userUnset 来对指定属性进行清空操作，如果该属性还未在集群中被创建，则 userUnset 不会创建该属性
// 清空该用户属性名为 userPropertykey 的用户属性值，即设置成 NULL
TDAnalytics.userUnset({
property: "userPropertykey"
});
userUnset 的传入值为被清空属性的 Key 值。
3.5 userDelete
如果您要删除某个用户，可以调用 userDelete将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到
TDAnalytics.userDelete();
3.6 userAppend
您可以调用 userAppend 对 Array (List) 类型的用户数据追加元素。
TDAnalytics.userAppend({
properties: {
user_list: ["apple", "ball"]
}
});
注意：该特性需要配合 AE 平台 2.5 及之后版本使用
3.7 userUniqAppend
自 v2.1.0 开始，您可以调用 userUniqAppend 对 Array (List) 类型的用户数据去重追加元素。
//此时user_list的属性值为["apple"，"ball"]
TDAnalytics.userAppend({
properties: {
user_list: ["apple", "ball"]
}
});
//此时user_list的属性值为["apple","apple","ball","cube"]
TDAnalytics.userAppend({
properties: {
user_list: ["apple", "cube"]
}
});
//此时user_list的属性值为["apple"，"ball","cube"]
TDAnalytics.userUniqAppend({
properties: {
user_list: ["apple", "cube"]
}
});
注意：该特性需要配合 AE 平台 3.6 及之后版本使用
五、其他功能
5.1 获取设备ID
您可以调用 getDeviceId() 获取设备 ID，由于运行环境的原因，设备 ID 会保存在本地缓存，一旦用户删除缓存，则设备 ID 将会变更，因此设备 ID 不能保证稳定不变
var deviceId = TDAnalytics.getDeviceId();
5.2 onComplete 回调函数
对于 track, userSet, userSetOnce, userAdd, userDelete 等接口，支持传入 onComplete 回调.
可以直接在原参数列表后传入 onComplete, 也可以使用参数对象的方式. 如果使用参数对象，参数对象中必须包含 onComplete, 否则会出现参数错误.
以上传事件为例：
TDAnalytics.track({
eventName: "test", // 必填
properties: { testkey: 123 }, // 可选
time: new Date(),
onComplete: res => {
console.log(res);
}
});
onComplete 的参数 res 为 object 类型，有两个属性 code 和 msg.
res.code 为 int 类型，定义如下:
- 0: 成功
- -1: 数据格式不正确
- -2: APP ID 无效
- -3: 网络或服务端异常
Debug 模式定义如下:
- 0: 成功
- -1: 参数或者权限校验的问题
- 1: 表示字段基本的错误, 会给出详细的错误字段和原由
- 2: 表示整条错误
- -3: 网络或服务端异常
res.msg 是对 res.code 的文字说明。
5.3 设置事件缓存上报
自 v2.2.0 开始，您可以在初始化的时候配置开启事件缓存上报。
// AE SDK 配置对象
var config = {
appId: "YOU-APP-ID", // 项目的 APP ID
serverUrl: "https://youserverurl.com", // 数据上报地址
enableBatch: true, // 是否开启事件缓存批量上报，true=开启，false=关闭
batchConfig: {
size: 5, // 事件缓存上报条数
interval: 5000 // 事件缓存上报间隔（毫秒）
}
};
// 初始化
TDAnalytics.init(config);
六、渠道SDK兼容
6.1 腾讯广告
6.1.1 方案简述
在集成了TDAnalytics SDK之后，您无需额外集成腾讯广告SDK。一旦您完成了TDAnalytics的初始化方法，系统会自动触发腾讯广告SDK的初始化。当您上报注册、付费等关键事件时，系统会根据您的配置自动将这些事件信息报送给腾讯广告。
6.1.2 接入流程
- 下载腾讯广告SDK，目前使用的是1.5.4版本，如果换成其他版本的也可以。
将dn-sdk-minigame.cjs.js跟TDAnalytics SDK放到同一目录下。
- 初始化
TDAnalytics SDK的版本需 >= 3.0.4
TDAnalytics.init({
appId: 'AppId',
serverUrl: 'ServerUrl',
tgaInitParams: {
user_action_set_id: 100001,// 数据源ID，数字，必填
secret_key: '5e853xxxxxxd57a690xxxxxxxxxx',// 加密key，必填
appid: 'wx123xyz123xyz123x',//微信小游戏APPID，wx开头，必填
},
reportingToTencentSdk: 2,//1 只上报给腾讯 2 同时上报给腾讯和AE 3 只上报给AE
debugMode: 'debug'// 如果是debug模式，会打印腾讯广告SDK本地调试日志
})
- 设置用户ID
- setOpenId
openid一般是调用后端接口异步获取的(获取openid方法)，请在获取到 openid 后调用 sdk.setOpenId() 方法设置。openid 和 unionid 只能设置一个，优先设置openid。
wx.request({
url: '后端获取openid以及判断是否注册用户的接口url',
success: function(res){
if(res.openid){
// 设置opneid，必须先设置openid再上报注册行为。setOpenId为同步方法，设置完可立即上报注册行为。
TDAnalytics.login(res.openid);
//上报注册行为，后台接口判断是否为注册用户
if(res.isRegisterUser){
TDAnalytics.track({
eventName: "REGISTER"
});
}
}
}
});
- setUnionId
unionid 一般是调用后端接口异步获取的(获取unionid方法)，请在获取到 unionid 后调用 sdk.setUnionId() 方法设置。没有openid才需使用此方法设置unionid。
wx.request({
url: '后端获取openid以及判断是否注册用户的接口url',
success: function(res){
if(res.unionid){
// 设置unionid ，请优先使用openid，没有openid 或者后台统一使用 unionid 才设置。
TDAnalytics.setDistinctId(res.unionid);
//上报注册行为，后台接口判断是否为注册用户
if(res.isRegisterUser){
TDAnalytics.track({
eventName: "REGISTER"
});
}
}
}
});
- 上报行为
TDAnalytics.track({
eventName: "product_buy", // 事件名称
properties: {
product_name: "商品名"
} //事件属性
});
如果是以下特定事件，需要上报指定的事件名称
| 事件 | 事件名 | 事件属性（需要包含其中的key） |
小游戏启动 | START_APP | 无 |
付费 | PURCHASE | { value: 600 } |
注册 | REGISTER | |
沉默唤起 | RE_ACTIVE | { backFlowDay: 30 } |
收藏小游戏 | ADD_TO_WISHLIST | { type: 'default', } |
分享小游戏 | SHARE | { target: 'APP_MESSAGE' } |
创建角色 | CREATE_ROL | { name: 'SuperMan' } |
完成新手指引 | TUTORIAL_FINISH | 无 |
游戏等级提升 | UPDATE_LEVEL | { level: 2, power: 85, } |
浏览商城页面 | VIEW_CONTENT | { // 关键场景访问：商城 item: 'Mall', } |
浏览游戏活动 | VIEW_CONTENT | { // 关键场景访问：活动 item: 'Activity', } |
比如上报游戏等级提升事件
TDAnalytics.track({
eventName: "UPDATE_LEVEL",
properties: {
level: 2,
power: 85,
}
});