# 进阶指南

# 一、设置用户 ID

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

# 1.1 设置访客 ID

提示

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

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

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

// 将访客ID设置为Thinker
ta.identify("Thinker");

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

//返回访客ID
String distinctId = await ta.getDistinctId();

# 1.2 设置账号ID

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

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

该方法不会上传登录事件

# 1.3 清除账号 ID

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

ta.logout();

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

该方法不会上传登出事件

# 二、发送事件

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

# 2.1 普通事件

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

ta.track('pruoduct_buy', properties: <String, dynamic>{'product_name': '商品名'});

# 2.2 首次事件

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

//示例：上报设备首次事件, 假设事件名为device_activation
var properties = {'key': 'value'};
var firstModel = TrackFirstEventModel('device_activation', '', properties);
ta.trackEventModel(firstModel);

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

// 将用户ID设置为首次事件的first_check_id，实现用户首次激活事件的采集
var properties = {'key': 'value'};
var firstModel = TrackFirstEventModel('account_activation', 'TA', properties);
ta.trackEventModel(firstModel);

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

# 2.3 可更新事件

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

// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
// 上报后事件属性 status 为 3, price 为 100
var properties = {
  'status': 3,
  'price': 100
};
var updateModel = TrackUpdateEventModel('UPDATABLE_EVENT', 'test_event_id', properties);
ta.trackEventModel(updateModel);

// 上报后事件属性 status 被更新为 5, price 不变
var properties_new = {
  'status': 5
};
var updateModel_new = TrackUpdateEventModel('UPDATABLE_EVENT', 'test_event_id', properties_new);
ta.trackEventModel(updateModel_new);

# 2.4 可重写事件

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

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITABLE_EVENT
// 上报后事件属性 status 为 3, price 为 100
var properties = {
    'status': 3,
    'price': 100
};
var overwriteModel = TrackOverwriteEventModel('OVERWRITABLE_EVENT', 'test_event_id', properties);
ta.trackEventModel(overwriteModel);

// 上报后事件属性 status 为 5, price属性被删除
var properties_new = {
    'status': 5
};
var overwriteModel_new = TrackOverwriteEventModel('OVERWRITABLE_EVENT', 'test_event_id', properties_new);
ta.trackEventModel(overwriteModel_new);

# 2.5 公共事件属性

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

# 2.5.1 静态公共事件属性

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

Map<String, dynamic> superProperties = {
  'vip_level': 2
};
ta.setSuperProperties(superProperties);

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

// 清除属性名为 SUPER_LIST 的公共属性
ta.unsetSuperProperty('SUPER_LIST');
// 清空所有公共属性
ta.clearSuperProperties();
//获取所有公共事件属性
ta.getSuperProperties();

# 2.5.2 动态公共事件属性

动态公共事件属性是高频变化且每个事件都会带有的属性，如用户的金币数量。通过 setDynamicSuperPropertiesTracker 设置动态公共属性类之后，SDK 将会在事件采集时自动获取动态公共事件属性，并添加到触发的事件中。设置动态公共属性，需要传入一个返回 Map<String, dyanmic> 类型的函数，样例如下：

// 设置动态公共属性, 动态公共属性不支持自动采集事件
ta.setDynamicSuperProperties((){
  return <String, dynamic> {
    'DYNAMIC_DATE': DateTime.now().toUtc(),
  };
});

动态公共属性目前不支持自动采集事件。

# 2.6 记录事件时长

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

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

# 三、用户属性

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

# 3.1 userSet

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

ta.userSet(<String, dynamic>{'user_name': 'TA'});  //此时username为TA
ta.userSet(<String, dynamic>{'user_name': 'TE'});  //此时userName为TE

属性格式要求与事件属性保持一致。

# 3.2 userSetOnce

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

//first_payment_time为2018-01-01 01:23:45.678
ta.userSetOnce(<String, dynamic>{'first_payment_time': '2018-01-01 01:23:45.678'});
//first_payment_time仍然为2018-01-01 01:23:45.678
ta.userSetOnce(<String, dynamic>{'first_payment_time': '2018-12-31 01:23:45.678'});

# 3.3 userAdd

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

 //此时total_revenue为30
ta.userAdd(<String, num>{ 'total_revenue': 30});
//此时total_revenue为678
ta.userAdd(<String, num>{ 'total_revenue': 648});

# 3.4 userUnset

如果您需要重置用户的某个属性，可以调用 userUnset 将该用户指定用户属性的值删除:

ta.userUnset('USER_INT');

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

# 3.5 userDelete

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

ta.userDelete();

# 3.6 userAppend

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

ta.userAppend(<String, List>{
  'USER_LIST': ['apple','ball'],
});

# 3.7 userUniqAppend

您可以调用 userUniqAppend 对数组类型的用户属性进行追加操作。调用 userUniqAppend 接口会对追加的用户属性进行去重， userAppend 接口不做去重，用户属性可存在重复。

//此时user_list的属性值为["apple"，"ball"]
ta.userAppend(<String, List>{ 'user_list': ['apple','ball']});
//此时user_list的属性值为["apple","apple","ball","cube"]
ta.userAppend(<String, List>{ 'user_list': ['apple','cube']});
//此时user_list的属性值为["apple"，"ball","cube"]
ta.useUniqrAppend(<String, List>{ 'user_list': ['apple','cube']});

# 四、加密功能

SDK 支持加密功能，客户端支持AES+RSA对数据进行加密，再由服务端对数据进行解密。加解密能力需要客户端和服务端配合完成，具体请咨询客户成功人员。您可以在SDK初始化时，开启数据传输加密功能。

var sKey = TASecretKey();
//配置版本号、公钥等密钥信息
sKey.publicKey =
    "xxx";
sKey.version = 1;
sKey.symmetricEncryption = "AES";
sKey.asymmetricEncryption = "RSA";
ThinkingAnalyticsAPI.getInstance(
    'APP_ID',
    'server_url',
    enableEncrypt: true,
    secretKey: sKey);

# 五、其他功能

# 5.1 获取设备ID

SDK 在初始化完成后，会自动生成设备 ID，并记录在本地缓存，对于同一应用/游戏，一台设备的设备 ID 是不变的，可以调用 getDeviceId 获取设备 ID：

String deviceId = await ta.getDeviceId();

// 以设备 ID 作为访客 ID
// ta.identify(deviceId);

# 5.2 设置默认时区

默认情况下，所有数据的发生时间都将设定为本机时间。如果你的产品分布在多个时区，并且希望将数据时间对其到指定时区，可以传入 timeZone 来设定时区。timeZone 需要是一个有效的时区字符串，例如 UTC, Asia/Shanghai 等。

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

ThinkingAnalyticsAPI.getInstance('APP_ID','server_url',timeZone:'UTC');

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

# 5.3 校准时间

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

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

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

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

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

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