进阶指南

一、设置用户ID

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

1.1 设置访客 ID

提示

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

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

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

// 将访客ID设置为Thinker
ThinkingAnalyticsAPI::Identify("Thinker");

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

//返回访客ID
ThinkingAnalyticsAPI::DistinctID().c_str()

1.2 设置账号 ID

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

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

该方法不会上传登录事件

1.3 清除账号ID

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

ThinkingAnalyticsAPI::LogOut();

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

该方法不会上传登出事件

二 、发送事件

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

2.1 普通事件

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

//商店购买事件
TDJSONObject event_properties;
event_properties.SetString("product_name", "商品名");
ThinkingAnalyticsAPI::Track("product_buy", event_properties);

2.2 首次事件

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

TDJSONObject jsonObject1;
jsonObject1.SetString("test","test");
TDFirstEvent *firstEvent = new TDFirstEvent("device_activation",jsonObject1);
ThinkingAnalyticsAPI::Track(firstEvent);
delete firstEvent;

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

//将用户ID设置为首次事件的first_check_id，实现用户首次激活事件的采集
TDJSONObject jsonObject1;
jsonObject1.SetString("test","test");
TDFirstEvent *firstEvent = new TDFirstEvent("account_activation",jsonObject1);
firstEvent->setFirstCheckId("TA");
ThinkingAnalyticsAPI::Track(firstEvent);
delete firstEvent;

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

2.3 可更新事件

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

// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
// 上报后事件属性 status 为 3, price 为 100
TDJSONObject jsonObject;
jsonObject.SetNumber("status", 3);
jsonObject.SetNumber("price", 100);
TDUpdatableEvent *updatableEvent = new TDUpdatableEvent("UPDATABLE_EVENT",jsonObject,"test_event_id");
ThinkingAnalyticsAPI::Track(updatableEvent);
delete updatableEvent;

// 上报后事件属性 status 被更新为 5, price 不变
TDJSONObject jsonObject1;
jsonObject1.SetNumber("status", 5);
TDUpdatableEvent *updatableEvent1 = new TDUpdatableEvent("UPDATABLE_EVENT",jsonObject1,"test_event_id");
ThinkingAnalyticsAPI::Track(updatableEvent1);
delete updatableEvent1;

2.4 可重写事件

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

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
// 上报后事件属性 status 为 3, price 为 100
TDJSONObject jsonObject;
jsonObject.SetNumber("status", 3);
jsonObject.SetNumber("price", 100);
TDOverWritableEvent *event = new TDOverWritableEvent("OVERWRITE_EVENT",jsonObject,"test_event_id");
ThinkingAnalyticsAPI::Track(event);
delete event;

// 上报后事件属性 status 被更新为 5, price 属性被删除
TDJSONObject jsonObject1;
jsonObject1.SetNumber("status", 5);
TDOverWritableEvent *event1 = new TDOverWritableEvent("OVERWRITE_EVENT",jsonObject1,"test_event_id");
ThinkingAnalyticsAPI::Track(event1);
delete event;

2.5 公共事件属性

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

2.5.1 静态公共事件属性

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

TDJSONObject superProperties;
superProperties.SetNumber("vip_level",2);
ThinkingAnalyticsAPI::SetSuperProperty(superProperties);

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

//清除某个公共事件属性
TDAnalytics.unsetSuperProperty("Channel");
//清除所有公共事件属性
ThinkingAnalyticsAPI::ClearSuperProperties();
//获取所有公共事件属性
TDJSONObject superJson;
ThinkingAnalyticsAPI::GetSuperProperties(superJson);

2.5.2 动态公共事件属性

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

TDJSONObject GetDynamicSuperProperties(){
    TDJSONObject json;
    json.SetNumber("coin",10);
    return json;
}
ThinkingAnalyticsAPI::Init(config);
ThinkingAnalyticsAPI::SetDynamicSuperProperties(GetDynamicSuperProperties);

2.6 记录事件时长

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

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

三、用户属性

TE 平台目前支持的用户属性设置接口有: UserSet、UserSetOnce、UserAdd、UserUnset、UserDelete、UserAppend.

3.1 UserSet

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

TDJSONObject userProperties;
userProperties.SetString("username", "TA");
ThinkingAnalyticsAPI::UserSet(userProperties);
//此时userName为TE
TDJSONObject userProperties1;
userProperties1.SetString("username", "TE");
ThinkingAnalyticsAPI::UserSet(userProperties1)

3.2 UserSetOnce

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

//first_payment_time为2018-01-01 01:23:45.678
TDJSONObject userProperties;
userProperties.SetString("first_payment_time","2018-01-01 01:23:45.678");
ThinkingAnalyticsAPI::UserSetOnce(userProperties);

//first_payment_time仍然为2018-01-01 01:23:45.678
TDJSONObject userProperties1;
userProperties1.SetString("first_pay_time","2018-12-31 01:23:45.678");
ThinkingAnalyticsAPI::UserSetOnce(userProperties1);

3.3 UserAdd

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

//此时total_revenue为30
TDJSONObject userProperties;
userProperties.SetNumber("total_revenue",30;
ThinkingAnalyticsAPI::UserAdd(userProperties);
//此时total_revenue为678
TDJSONObject userProperties1;
userProperties1.SetNumber("total_revenue",648);
ThinkingAnalyticsAPI::UserAdd(userProperties1);

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

3.4 UserUnset

如果您需要重置用户的某个属性，可以调用 UserUnset 将该用户指定用户属性的值清空，此接口支持传入字符串或者列表类型的参数:

ThinkingAnalyticsAPI::UserUnset("userUnset_key");

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

3.5 UserDelete

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

ThinkingAnalyticsAPI::UserDelete();

3.6 UserAppend

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

TDJSONObject userProperties;
vector<string> listValue;
listValue.push_back("apple");
listValue.push_back("ball");
userProperties.SetList("user_list",listValue);
ThinkingAnalyticsAPI::UserAppend(userProperties);

3.7 UserUniqAppend

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

//此时user_list的属性值为["apple"，"ball"]
TDJSONObject userProperties1;
vector<string> listValue1;
listValue1.push_back("apple");
listValue1.push_back("ball");
userProperties1.SetList("user_list",listValue1);
ThinkingAnalyticsAPI::UserAppend(userProperties1);

//此时user_list的属性值为["apple","apple","ball","cube"]
TDJSONObject userProperties2;
vector<string> listValue1;
listValue2.push_back("apple");
listValue2.push_back("cube");
userProperties2.SetList("user_list",listValue2);
ThinkingAnalyticsAPI::UserAppend(userProperties2);

//此时user_list的属性值为["apple"，"ball","cube"]
ThinkingAnalyticsAPI::UserUniqAppend(userProperties2);

四、加密功能

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

TDConfig config;
config.appid = appid;
config.server_url = server_url;
config.EnableEncrypt(1,"publickKey");
ThinkingAnalyticsAPI::Init(config);

五、其他功能

4.1 打印SDK日志

可以通过EnableLog接口,打开SDK日志开关，打开后将会IDE控制台打印上报的数据。

ThinkingAnalyticsAPI::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
ThinkingAnalyticsAPI::CalibrateTime(1585633785954);

• 您也可以设置自动时间校准，之后 SDK 会尝试从 config接口中获取当前时间，并对 SDK 时间进行校准。如果未获取正确的返回结果，后续将使用本地时间上报数据。

TDConfig config;
config.appid = appid;
config.server_url = server_url;
config.enableAutoCalibrated = true;
ThinkingAnalyticsAPI::Init(config);

4.5 立即发送数据

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

ThinkingAnalyticsAPI::Flush();

4.6 获取设备ID

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

ThinkingAnalyticsAPI::GetDeviceId();