跳到主要内容

进阶指南

最近更新 2026/10/05

一、设置用户ID​

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

1.1 设置访客 ID​

提示

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

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

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

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

//返回访客ID
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。

// 去除上报数据里的 "#account_id"，之后的数据将不带有 "#account_id"
TDAnalytics.logout();

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

该方法不会上传登出事件

二 、发送事件​

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

2.1 普通事件​

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

TDAnalytics.track("product_buy", // 事件名称
    {
        product_name: "商品名"
    } //事件属性
);

2.2 首次事件​

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

TDAnalytics.trackFirst("device_activation",{ key: "value" });

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

// 将用户ID设置为首次事件的first_check_id，实现用户首次激活事件的采集
TDAnalytics.trackFirst("account_activation",{ key: "value" },"TA");

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

2.3 可更新事件​

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

// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
// 上报后事件属性 status 为 3, price 为 100
TDAnalytics.trackUpdate("UPDATABLE_EVENT",{ status: 3, price: 100 },"test_event_id");

// 上报后事件属性 status 被更新为 5, price 不变
TDAnalytics.trackUpdate("UPDATABLE_EVENT",{ status: 5 },"test_event_id");

2.4 可重写事件​

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

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
// 上报后事件属性 status 为 3, price 为 100
TDAnalytics.trackOverwrite("OVERWRITE_EVENT",{ status: 3, price: 100 },"test_event_id");

// 上报后事件属性 status 被更新为 5, price 属性被删除
TDAnalytics.trackOverwrite("OVERWRITE_EVENT",{ status: 5 },"test_event_id");

2.5 公共事件属性​

对于一些重要的属性，譬如用户的设备 ID、来源渠道、用户状态等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共属性，即每个事件中都带有的属性。我们推荐您在发送事件前，先设置公共属性。

公共属性包含两种，静态公共事件属性和动态公共事件属性。在事件上报时，公共属性将会被插入到数据的 properties 中。如果此时公共属性与事件中设置的自定义属性有相同 key 值，则属性会根据下述优先级判断该取什么值：自定义属性>动态公共事件属性>静态公共事件属性>预置属性。

2.5.1 静态公共事件属性​

对于一些重要的属性，譬如用户的渠道、昵称、ID 等，这些属性需要设置在每个事件中，您可以调用setSuperProperties 来设置静态公共事件属性，静态公共事件属性会对全局生效。当开启缓存时（默认打开），静态公共属性会缓存下来，下次启动仍然生效。

静态公共属性的参数是一个 JSON 对象，其格式要求与事件属性保持一致。

// 设置公共事件属性，所有数据事件中都会带有这些属性
TDAnalytics.setSuperProperties({
     channel: "渠道名",
     user_name: "用户名"
});

除了属性设置，我们也提供其他API来操作静态公共事件属性，满足日常的业务需求。

// 获取静态公共事件属性
TDAnalytics.getSuperProperties();
// 清除一条静态公共事件属性，比如将之前设置 'channel' 属性清除，之后的数据将不会该属性
TDAnalytics.unsetSuperProperty("channel");
// 清除所有静态公共事件属性
TDAnalytics.clearSuperProperties();

2.5.2 动态公共事件属性​

通过 setDynamicSuperProperties 设置动态公共属性的回调函数，SDK 将会在事件上报时触发回调函数，并把返回 JSON 对象加入到事件属性中。setDynamicSuperProperties 的参数是一个函数，函数需要返回一个 JSON 对象。

// 设置动态公共属性，在事件上报时触发回调函数，并把返回的JSON对象加入到事件属性中
TDAnalytics.setDynamicSuperProperties(function() {
    var d = new Date();
    d.setHours(10);
    return { date: d };
});

2.6 记录事件时长​

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

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

三、用户属性​

AE 平台支持的用户属性设置API有: userSet、userSetOnce、userAdd、userUnset、userDelete、userAppend、userUniqAppend。

3.1 userSet​

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

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

3.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" 
});

3.3 userAdd​

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

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

3.4 userUnset​

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

// 清空该用户属性名为 userPropertykey 的用户属性值，即设置成 NULL
TDAnalytics.userUnset("userPropertykey");

3.5 userDelete​

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

TDAnalytics.userDelete();

3.6 userAppend​

您可以调用 userAppend 对数组类型的用户数据追加元素。

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

3.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，并设置默认版本号和公钥。

var config = {
  appId: "YOUR_APP_ID", // 项目 APP ID
  serverUrl: "YOUR_SERVER_URL", // 上报地址
  enableEncrypt: true, // 开启数据传输加密
  secretKey: {
    publicKey:'YOUR_PUBLIC_KEY', // 加密公钥
    version:0 // 密钥版本号
   }
};
// 初始化
TDAnalytics.init(config);

五、其他功能​

5.1 获取设备ID​

您可以调用 getDeviceId() 获取设备 ID。

TDAnalytics.getDeviceId();

设备 ID 会保存在缓存中，用户清理缓存，设备ID会被重置。

5.2 设置事件缓存上报​

您可以在初始化的时候配置开启事件缓存上报。暂时只支持uni-app，Android、iOS、鸿蒙平台默认采用缓存批量上报，无法额外设置。

// 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);

5.3 设置默认时区​

默认情况下,SDK 默认会使用接口调用时的本机时间作为事件发生时间上报。自v3.0.3开始，您也可以通过初始化时设置默认时区，这样所有的事件都将按照您设置的时区来对齐事件时间：

var config = {
  appId: "YOU-APP-ID", // 项目的 APP ID
  serverUrl: "https://youserverurl.com", // 数据上报地址
  zoneOffset:8
};

注意：用指定时区对齐事件时间，会丢掉设备本机时区信息。如果需要保留设备本机时区信息，目前需要您自己为事件添加相关属性。

这篇文档对你有帮助吗？
本页内容