进阶指南

最近更新 2026/10/03

一、设置用户 ID

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

1.1 设置访客 ID

提示

一般情况下，您不需要自定义访客 ID。请确保已经理解用户识别规则，再进行访客 ID 的设置。

如果您需要替换访客 ID，则应当在初始化 SDK 结束之后立即进行调用，请勿多次调用，以免产生无用的账号

如果您的 App 对每个用户有自己的访客 ID 管理体系，则您可以调用 setDistinctId 来设置访客 ID：

// 将访客ID设置为Thinker
TDAnalytics.setDistinctId("Thinker");

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

//返回访客ID
async () => {
  var distinct_id = await TDAnalytics.getDistinctId()
}

1.2 设置账号ID

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

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

该方法不会上传登录事件

1.3 清除账号 ID

在用户产生登出行为之后，可调用 logout 来清除账号 ID，在下次调用 login 之前，将会以访客 ID 作为身份识别 ID。

TDAnalytics.logout();

我们推荐您在显性的登出事件时调用 logout，比如用户产生了注销账号这一行为时才调用，而不需要在关闭 App 时调用。

该方法不会上传登出事件

二、发送事件

2.1 普通事件

在 SDK 初始化完成之后，您就可以进行数据埋点，收集用户的的行为信息。一般情况下普通事件即可满足业务场景需求，您也可以根据自己的实际业务场景使用首次、可更新等事件。

//商店购买事件
TDAnalytics.track({
    eventName:"product_buy",
    properties:{
      'product_name':'商品名'
    }
})   

2.2 首次事件

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

// 示例：上报设备首次事件, 假设事件名为 device_activation
TDAnalytics.trackFirst({
    eventName:'device_activation',
    properties: {
        KEY_NUMBER: 1.02,
        KEY_STRING: "name",
        KEY_LIST: [1, 2, 3],
        KEY_BOOL: true,
        KEY_DateTime: "2020-05-12 06:27:18.371"
    }
})

如果您希望以设备以外的其他维度来判断是否首次，则可以为首次事件自定义first_check_id:

// 将用户ID设置为首次事件的first_check_id，实现用户首次激活事件的采集
TDAnalytics.trackFirst({
    eventName:'device_activation',
    properties: {
        KEY_NUMBER: 1.02,
        KEY_STRING: "name",
        KEY_LIST: [1, 2, 3],
        KEY_BOOL: true,
        KEY_DateTime: "2020-05-12 06:27:18.371"
    },
    eventId:'TA'
})

注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 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 公共事件属性

公共事件属性指的就是每个事件都会上传的属性。根据属性更新频率，公共事件属性分为静态公共事件属性和动态公共事件属性。您可以根据具体的业务场景需求，选择不同的公共事件属性设置方法；我们推荐您在发送事件前，先设置公共事件属性。针对同一事件，当公共事件属性、事件自定义属性、预置属性的Key相同时，我们会按照如下优先级进行赋值:自定义属性>动态公共事件属性>静态公共事件属性>预置属性。

2.5.1 设置静态公共事件属性

静态公共事件属性是低频变化且每个事件都会带有的属性，如用户会员等级。通过setSuperProperties设置静态公共事件属性之后，SDK将会在事件采集时获取设置的公共事件属性作为事件的属性。

TDAnalytics.setSuperProperties({ vip_level: 2})

静态公共事件属性将会被保存到缓存中，无需每次启动 App 时调用。如果该属性已存在，重新设置的属性将会覆盖原有属性值。如果之前不存在该属性，则会新建属性。除了属性设置，我们也提供其他API来操作静态公共事件属性，满足日常的业务需求。

//清除某个公共事件属性
TDAnalytics.unsetSuperProperty("superKey")
//清除所有公共事件属性
TDAnalytics.clearSuperProperties()
//获取所有公共事件属性
async () => {
  var properties = await TDAnalytics.getSuperProperties()
}

2.5.2 设置动态公共事件属性

动态公共事件属性是高频变化且每个事件都会带有的属性，如用户的金币数量。通过 setDynamicSuperPropertiesTracker 设置动态公共属性类之后，SDK 将会在事件采集时自动获取 getDynamicSuperProperties 中的属性，并添加到触发的事件中。

var coin = 0;
TDAnalytics.setDynamicSuperProperties(function () {
    return { coin: coin++ }
 })

2.6 记录事件时长

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

//以下示例，完成用户在某个商品页面停留时长的统计
 //用户进入商品页面，开始计时
TDAnalytics.timeEvent("stay_shop")
/**do someting
    .......
    **/
//用户离开商品页面，计时结束，"stay_shop" 这一事件中将会带有表示事件时长的属性#duration
TDAnalytics.track({eventName:"stay_shop"})  

三、用户属性

AE 平台目前支持的用户属性设置接口为 userSet、userSetOnce、userAdd、userUnset、userDelete 、 userAppend、userUniqAppend

4.1 userSet

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

// username为TA
TDAnalytics.userSet({ username: "TA" });
//username为AE
TDAnalytics.userSet({ username: "AE" });

4.2 userSetOnce

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

//first_payment_time为2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({first_payment_time: "2018-01-01 01:23:45.678" });
//first_payment_time仍然为2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({first_payment_time: "2018-12-31 01:23:45.678" });

4.3 userAdd

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

//此时total_revenue为30
TDAnalytics.userAdd({ total_revenue: 30 });
//此时total_revenue为678
TDAnalytics.userAdd({ total_revenue: 648 });

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

4.4 userUnset

当您要清空用户的用户属性值时，您可以调用 userUnset 来对指定属性进行清空操作，如果该属性还未在集群中被创建，则 userUnset 不会创建该属性

TDAnalytics.userUnset("usersetkey")

userUnset 传入的参数是用户属性的属性名，类型是字符串或字符串数组，支持可变长参数的形式。

4.5 userDelete

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

TDAnalytics.userDelete()

4.6 userAppend

您可以调用 userAppend 对 Array 类型的用户属性进行追加操作。

TDAnalytics.userAppend({ user_list: ["apple", "ball"] });

4.7 userUniqAppend

您可以调用 userUniqAppend 对 Array (List) 类型的用户数据追加唯一元素。调用 userUniqAppend 接口会对追加的用户属性进行去重， userAppend 接口不做去重，用户属性可存在重复。

//此时user_list的属性值为["apple","ball"]
TDAnalytics.userAppend({ user_list: ["apple", "ball"] });
//此时user_list的属性值为["apple","apple","ball","cube"]
TDAnalytics.userAppend({ user_list: ["apple", "cube"] });
//此时user_list的属性值为["apple","ball","cube"]
TDAnalytics.userUniqAppend({ user_list: ["apple", "cube"] });

四、加密功能

SDK 支持加密功能，客户端支持 AES + RSA 对数据进行加密，再由服务端对数据进行解密，加解密能力需要客户端和服务端配合完成，具体请咨询客户成功人员。

设置 enableEncrypt 属性为true，并设置默认版本号和公钥。

import TDAnalytics, { TDAutoTrackEventType,TDThirdPartyType,TDTrackStatus} from "react-native-thinking-data";
TDAnalytics.init({
    appId: "xxx",
    serverUrl: "https://xxx",
    enableEncrypt: true,// 开启数据传输加密
    secretKey: {
        publicKey: "xxx",// 加密公钥
        version: 1,// 密钥版本号
        symmetricEncryption: "AES",
        asymmetricEncryption: "RSA"
    }
});

五、开启与 H5 页面的打通

如果需要与采集 H5 页面数据的 JavaScript SDK 进行打通，请调用如下接口，详情请参考 H5 与 APP SDK 打通一节

<WebView
  ref={webViewRef}
  source={localHtmlFile}
  onMessage={ event => {
    console.log(event.nativeEvent.data);
    TDAnalytics.h5ClickHandler(event.nativeEvent.data);
  }}
  javaScriptEnabled={true}
  injectedJavaScript='window.ThinkingData_APP_ReactNative_Bridge = function(data) { window.ReactNativeWebView.postMessage(data); };'
/>

六、其他功能

6.1 获取设备ID

您可以通过调用 getDeviceId 来获取设备 ID：

async () => {
  var device_id = await TDAnalytics.getDeviceId()
}

6.2 校准时间

SDK 默认会使用本机时间作为事件发生时间上报，如果用户手动修改设备时间会影响到您的业务分析，此时可以通过校准时间操作保证事件发生时间的准确性。我们提供时间戳、NTP两种时间校准方式。

• 您可以使用从服务端获取的当前时间戳对 SDK 的时间进行校准。此后，所有未指定时间的调用，包括事件数据和用户属性设置操作，都会使用校准后的时间作为发生时间。

// 1585633785954 为当前 unix 时间戳，单位为毫秒，对应北京时间 2020-03-31 13:49:45
TDAnalytics.calibrateTime(1585633785954);

• 您也可以设置NTP服务器地址，之后 SDK 会尝试从传入的 NTP 服务地址中获取当前时间，并对 SDK 时间进行校准。如果在默认的超时时间（3 秒）之内，未获取正确的返回结果，后续将使用本地时间上报数据。

// 使用苹果公司 NTP 服务对时间进行校准
TDAnalytics.calibrateTimeWithNtp("time.apple.com");

1、使用 NTP 服务进行时间校准存在一定的不确定性，建议您优先考虑用时间戳校准的方式

2、您需要谨慎地选择您的 NTP 服务器地址，以保证网络状况良好的情况下，用户设备可以很快的获取到服务器时间

6.3 立即上报数据

在某些业务场景下，如果您期望数据立即上报到 AE 服务器，可以通过调用flush接口完成

TDAnalytics.flush();