跳到主要内容

进阶指南

最近更新 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
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。

// 清除账号 ID
TDAnalytics.Logout();

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

该方法不会上传登出事件

二 、发送事件​

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

2.1 普通事件​

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

Dictionary<string, Object> dic = new Dictionary<string, object>();
dic.Add("product_name", "商品名");
TDAnalytics.Track( "product_buy",dic);

2.2 首次事件​

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

Dictionary<string, object> dic = new Dictionary<string, object>();
dic.Add("key", "value");
TDFirstEvent firstEventModel = new TDFirstEvent("device_activation", dic);
TDAnalytics.Track(firstEventModel);

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

// 将用户ID设置为首次事件的first_check_id，实现用户首次激活事件的采集
Dictionary<string, object> dic = new Dictionary<string, object>();
dic.Add("key", "value");
TDFirstEventModel firstEventModel = new TDFirstEventModel("device_activation", dic, "TA");
TDAnalytics.Track(firstEventModel);

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

2.3 可更新事件​

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

// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
// 上报后事件属性 status 为 3, price 为 100
Dictionary<string, Object> dic = new Dictionary<string, object>();
dic.Add("price", 100);
dic.Add("status",3);
TDUpdatableEventModel updatableEventModel = new TDUpdatableEventModel("UPDATABLE_EVENT", dic, "updateEventId");
TDAnalytics.Track(updatableEventModel);

// 上报后事件属性 status 被更新为 5, price 不变
Dictionary<string, Object> dic1 = new Dictionary<string, object>();
dic1.Add("status",5);
TDUpdatableEventModel updatableEventModel_new = new TDUpdatableEventModel("UPDATABLE_EVENT", dic1,"updateEventId");
TDAnalytics.Track(updatableEventModel_new);

2.4 可重写事件​

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

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITABLE_EVENT
// 上报后事件属性 status 为 3, price 为 100
Dictionary<string, Object> dic = new Dictionary<string, object>();
dic.Add("price", 100);
dic.Add("status",3);
TDOverwritableEventModel overwritableEventModel = new TDOverwritableEventModel("OVERWRITABLE_EVENT", dic,"eventId");
TDAnalytics.Track(overwritableEventModel);

// 上报后事件属性 status 被更新为 5, price 属性被删除
Dictionary<string, Object> dic1 = new Dictionary<string, object>();
dic1.Add("status",5);
TDOverwritableEventModel overwritableEventModel_new = new TDOverwritableEventModel("OVERWRITABLE_EVENT", dic1,"eventId");
TDAnalytics.Track(overwritableEventModel_new);

2.5 公共事件属性​

公共事件属性指的就是每个事件都会上传的属性。

2.5.1 静态公共事件属性​

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

Dictionary<string, object> superProperties = new Dictionary<string, object>();
superProperties["vip_level"] = 2;
TDAnalytics.SetSuperProperties(superProperties);

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

//清除某个公共事件属性
TDAnalytics.UnsetSuperProperties("Channel");
//清除所有公共事件属性
TDAnalytics.ClearSuperProperties();
//获取所有公共事件属性
var superProperties = TDAnalytics.GetSuperProperties();

2.5.2 动态公共事件属性​

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

static Dictionary<string, object> GetDynamicSuperProperties()
{
    return new Dictionary<string, object> { { "coin", 10 } };
}

TDAnalytics.Init(config);
TDAnalytics.SetDynamicSuperProperties(GetDynamicSuperProperties);

2.6 记录事件时长​

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

//用户进入商品页面，开始计时
TDAnalytics.TimeEvent("stay_shop");
/**do someting
.......
**/
//用户离开商品页面，计时结束，"stay_shop" 这一事件中将会带有表示事件时长的属性#duration
TDAnalytics.Track("stay_shop");

三、用户属性​

AE 平台支持的用户属性设置API有: UserSet、UserSetOnce、UserAdd、UserUnset、UserDelete、UserAppend。

3.1 UserSet​

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

//此时user_name为TA
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
//此时user_name为AE
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "AE"}});

3.2 UserSetOnce​

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

//first_pay_time为2018-01-01 01:23:45.678
TDAnalytics.UserSetOnce(new Dictionary<string, object>(){{"first_pay_time","2018-01-01 01:23:45.678"}});
 //first_pay_time仍然为2018-01-01 01:23:45.678
TDAnalytics.UserSetOnce(new Dictionary<string, object>(){{"first_pay_time","2018-12-31 01:23:45.678"}});

3.3 UserAdd​

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

//此时total_revenue为30
TDAnalytics.UserAdd(new Dictionary<string, object>(){{"total_revenue",30}});
//此时total_revenue为678
TDAnalytics.UserAdd(new Dictionary<string, object>(){{"total_revenue",648}});

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

3.4 UserUnset​

如果您需要重置用户的某个属性，可以调用 UserUnset 将该用户指定用户属性的值清空。

TDAnalytics.UserUnset("nickname");

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

3.5 UserDelete​

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

TDAnalytics.UserDelete();

3.6 UserAppend​

您可以调用 UserAppend 为 List 类型的用户属性追加元素:

Dictionary<string, object> dictionary = new Dictionary<string, object>();
List<string> list6 = new List<string>();
list6.Add("true");
list6.Add("test");
dictionary.Add("arrkey4", list6);
TDAnalytics.UserAppend( dictionary);

3.7 UserUniqAppend​

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

//此时user_list的属性值为["apple"，"ball"]
Dictionary<string, Object> dic = new Dictionary<string, object>();
List<string> list = new List<string>();
list.Add("apple");
list.Add("ball");
dic.Add("user_list", list);
TDAnalytics.UserAppend(dic);
//此时user_list的属性值为["apple","apple","ball","cube"]
Dictionary<string, Object> dic1 = new Dictionary<string, object>();
List<string> list1 = new List<string>();
list1.Add("apple");
list1.Add("cube");
dic1.Add("user_list", list1);
TDAnalytics.UserAppend(dic1);
//此时user_list的属性值为["apple"，"ball","cube"]
Dictionary<string, Object> dic2 = new Dictionary<string, object>();
List<string> list2 = new List<string>();
list2.Add("apple");
list2.Add("cube");
dic2.Add("user_list", list2);
TDAnalytics.UserUniqAppend(dic2);

四、加密功能​

从 v2.0.0-beta.1 版本开始，SDK 支持使用AES+RSA加密数据。数据加密功能需要客户端和服务端配合完成，具体使用方法请咨询客户成功人员。

TDConfig config = new TDConfig();
config.AppId = appid;
config.ServerUrl = server_url;
config.EnableEncrypt = true;
config.Version = 1;
config.PublicKey = "publickKey";
TDAnalytics.Init(config);

五、其他功能​

5.1 打印SDK日志​

// 开启后会在项目根目录的 ta_event_log.txt 文件查看日志
TDAnalytics.EnableLogType(TDLogType.LogTxt);

5.2 预置属性说明​

属性名中文名属性类型说明
#ip

IP 地址

文本用户的 IP 地址，AE 将以此获取用户的地理位置信息
#country国家文本用户所在国家，根据 IP 地址生成

#country_code

国家代码

文本用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成
#province省份文本用户所在省份，根据 IP 地址生成
#city城市文本用户所在城市，根据 IP 地址生成
#os操作系统文本如 MacOS,Windows等
#device_id设备 ID文本用户的设备 ID

#lib

SDK 类型文本您接入 SDK 的类型，如 Android，iOS 等
#lib_versionSDK 版本文本您接入 SDK 的版本

5.3 时间校准​

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

  • 您可以使用从服务端获取的当前时间戳对 SDK 的时间进行校准。此后，所有未指定时间的调用，包括事件数据和用户属性设置操作，都会使用校准后的时间作为发生时间。
// 1585633785954 为当前 unix 时间戳，单位为毫秒，对应北京时间 2020-03-31 13:49:45
TDAnalytics.CalibrateTime(1585633785954);
  • 您也可以设置自动时间校准，之后 SDK 会尝试从 config接口中获取当前时间，并对 SDK 时间进行校准。如果未获取正确的返回结果，后续将使用本地时间上报数据。
TDConfig config = new TDConfig();
config.AppId = appid;
config.ServerUrl = server_url;
config.EnableAutoCalibrated = true;
TDAnalytics.Init(config);

5.4 立即发送数据​

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

TDAnalytics.Flush();

5.5 获取设备ID​

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

TDAnalytics.GetDeviceId();

5.6 设置默认时区​

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

TDConfig config = new TDConfig();
config.AppId = appid;
config.ServerUrl = server_url;
config.ZoneOffset = 5;
TDAnalytics.Init(config);

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

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