进阶指南

一、设置用户ID

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

1.1 设置访客 ID

提示

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

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

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

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

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

//返回访客ID
TDAnalytics.GetDistinctId()

1.2 设置账号 ID

在用户进行登录时，可调用 Login 来设置用户的账号 ID， TE 平台将会以账号 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");
TDFirstEventModel firstEventModel = new TDFirstEventModel("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，并在创建可更新事件对象时传入。TE 后台将根据事件名和事件 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 TDUpdatableEventModel("UPDATABLE_EVENT", dic1,"updateEventId");
TDAnalytics.Track(updatableEventModel);

2.4 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。TE 后台将根据事件名和事件 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 TDOverwritableEventModel("OVERWRITABLE_EVENT", dic1,"eventId");
TDAnalytics.Track(overwritableEventModel);

三、用户属性

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

3.1 UserSet

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

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

3.2 UserSetOnce

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

//first_payment_time为2018-01-01 01:23:45.678
TDAnalytics.UserSetOnce(new Dictionary<string, object>(){{"first_pay_time","2018-01-01 01:23:45.67"}});
 //first_payment_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 将该用户指定用户属性的值清空，此接口支持传入字符串或者列表类型的参数:

List<string> list2 = new List<string>();
list2.Add("nickname");
list2.Add("age");
TDAnalytics.UserUnSet(list2);

传入值为被清空属性的 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);

四、其他功能

4.1 打印上传数据 Log

TDAnalytics.EnableLog(true);

4.2 预置属性说明

属性名	中文名	属性类型	说明
#ip	IP 地址	文本	用户的 IP 地址，TE 将以此获取用户的地理位置信息
#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_version	SDK 版本	文本	您接入 SDK 的版本

4.3 时间校准

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

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

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