ae-tracking 0.1.0

package/wiki/te-docs/raw//346/216/245/345/205/245/346/214/207/345/215/227//345/256/242/346/210/267/347/253/257-sdk/c//350/277/233/351/230/266/346/214/207/345/215/227.md

@@ -0,0 +1,477 @@
+---
+code: client_cpp_sdk_advanced
+name: "进阶指南"
+wikiToken: OlznwgrzoieRjPkq1VdcUuwmnbe
+parentWikiToken: E8ekwJ170iMfb8ktBPfcYxE4nq0
+updateTime: 1745310911000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=client_cpp_sdk_advanced
+---
+# 进阶指南
+
+### 一、设置用户ID
+
+SDK 实例默认会使用随机数作为每个用户的默认访客 ID，该 ID 将会作为用户在未登录状态下身份识别 ID。需要注意的是，访客 ID 在用户重新安装应用以及更换设备时将会变更。
+
+#### 1.1 设置访客 ID
+
+::: tip 提示
+
+ 一般情况下，您不需要自定义访客 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， AE 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 `Logout` 之前一直保留。多次调用 `Login` 将覆盖先前的账号 ID 
+
+```
+// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
+ThinkingAnalyticsAPI::Login("TA");
+```
+
+<!-- unsupported block: 34 -->
+
+**该方法不会上传登录事件**
+
+#### 1.3 清除账号ID
+
+在用户产生登出行为之后，可调用 `LogOut` 来清除账号 ID，在下次调用 `Login` 之前，将会以访客 ID 作为身份识别 ID。
+
+```
+ThinkingAnalyticsAPI::LogOut();
+```
+
+我们推荐您在显性的登出事件时调用 `LogOut`，比如用户产生了注销账号这一行为时才调用，而不需要在关闭 App 时调用。
+
+<!-- unsupported block: 34 -->
+
+**该方法不会上传登出事件**
+
+### 二 、发送事件
+
+在 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;
+```
+
+<!-- unsupported block: 34 -->
+
+注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 1 小时入库。
+
+#### 2.3 可更新事件
+
+您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。AE 后台将根据事件名和事件 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 可重写事件
+
+可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。AE 后台将根据事件名和事件 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();
+}
+```
+
+### 三、用户属性
+
+AE 平台目前支持的用户属性设置接口有: `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);
+```
+
+<!-- unsupported block: 34 -->
+
+设置的属性key为字符串，Value 只允许为数值。
+
+#### 3.4 UserUnset
+
+如果您需要重置用户的某个属性，可以调用 `UserUnset` 将该用户指定用户属性的值清空，此接口支持传入字符串或者列表类型的参数:
+
+```
+ThinkingAnalyticsAPI::UserUnset("userUnset_key");
+```
+
+<!-- unsupported block: 34 -->
+
+传入值为被清空属性的 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);
+```
+
+### 五、其他功能
+
+#### 5.1 打印SDK日志
+
+可以通过EnableLog接口,打开SDK日志开关，打开后将会IDE控制台打印上报的数据。
+
+```
+ThinkingAnalyticsAPI::EnableLog(true);
+```
+
+#### 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_version
+
+SDK 版本
+
+文本
+
+您接入 SDK 的版本
+
+#### 5.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);
+```
+
+#### 5.4 立即发送数据
+
+在某些业务场景下，如果您期望数据立即上报到 AE 服务器，可以通过调用`flush`接口完成
+
+```
+ThinkingAnalyticsAPI::Flush();
+```
+
+#### 5.5 获取设备ID
+
+您可以通过调用 `getDeviceId` 来获取设备 ID：
+
+```
+ThinkingAnalyticsAPI::GetDeviceId();
+```
+
+#### 5.6 设置默认时区
+
+默认情况下，SDK 默认会使用接口调用时的本机时间作为事件发生时间上报。您也可以通过设置默认时区接口，指定默认的时区，这样所有的事件都将按照您设置的时区来对齐事件时间：
+
+```
+TDConfig config;
+config.appid = appid;
+config.server_url = server_url;
+config.zoneOffset = 5;
+ThinkingAnalyticsAPI::Init(config);
+```
+
+<!-- unsupported block: 34 -->
+
+注意：用指定时区对齐事件时间，会丢掉设备本机时区信息。如果需要保留设备本机时区信息，目前需要您自己为事件添加相关属性。

package/wiki/te-docs/raw//346/216/245/345/205/245/346/214/207/345/215/227//345/256/242/346/210/267/347/253/257-sdk/c-Uicgw2.md

@@ -0,0 +1,145 @@
+---
+code: client_csharp_sdk_installation
+name: "C#"
+wikiToken: Uicgw2qEcizaeMk7k42cWndNnAe
+parentWikiToken: FTcTwinIOi3OiRkK4MPc2Ex7neg
+updateTime: 1760333667000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=client_csharp_sdk_installation
+---
+# C#
+
+::: tip 提示
+
+ 在接入前, 请先阅读接入前准备。
+
+C# SDK 支持在Windows、Mac平台运行。
+
+ :::
+
+**最新版本:** 2.0.1
+
+**更新时间:** 2025-10-13
+
+**资源下载: **SDK源码 下载
+
+::: warning 注意
+
+当前文档适用于 v2.0.0 及以后的版本，历史版本请参考 C# 接入指南（旧）
+
+::: 
+
+### 一、集成SDK
+
+### 1.1 下载SDK
+
+下载在 GitHub 获取C# SDK 源码，将`TDAnalyticsSDK`目录下的文件添加至项目中。
+
+SDK依赖Newtonsoft.Json框架用作json解析，如您是使用`Visual Studio`，请使用`NuGet`加入`Newtonsoft.Json`库。
+
+### 1.2 添加动态库
+
+- 下载dll，然后解压（下载任意一个即可）
+- github链接
+- 官网链接
+- Windows平台，可以找到windowswen文件夹下的dll文件，复制到项目根目录即可。（注意：如果dll和项目已有dll冲突，使用项目已有的即可）
+- Mac平台
+- 第一步：通过homebrew安装sqlite、curl、zlib 、openssl这4个库
+- 第二步：找到macOS文件夹下的dll文件，复制到项目根目录即可
+### 二、初始化
+
+引入`ThinkingData.Analytics`，使用ThinkingdataAnalytics类初始化 AE 实例。
+
+```
+using ThinkingData.Analytics;
+TDAnalytics.Init(APPID,SERVER_URL)
+```
+
+参数说明:
+
+- `APPID`: 您的项目的 APPID，可通过在 AE 后台项目管理页面获取
+- `SERVER_URL`: 数据上传的 URL
+- 如果您对接的是云服务，填入: https://global-receiver-ta.thinkingdata.cn
+- 如果您使用私有化部署版本，请为数据采集地址绑定域名，并配置 HTTPS 证书：https://数据采集地址绑定域名
+### 三、常用功能
+
+在使用常用功能之前，建议你先了解用户识别规则；SDK默认会生成随机数作为访客ID，并持久化存储访客ID在本地；用户未登录之前，会以访客ID作为身份识别ID。注意:访客 ID 在用户重新安装 App 以及更换设备时将会变更。
+
+#### 3.1 设置账号ID
+
+在用户进行登录时，可调用 `Login` 来设置用户的账号 ID， AE 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 `Logout` 之前一直保留。多次调用 `Login` 将覆盖先前的账号 ID 。
+
+```
+TDAnalytics.`Login`("TA");
+```
+
+`Login` 可以多次调用，每次调用会判断传入的账号 ID 与先前保存的 ID 是否一致，一致则忽略调用，不一致则会覆盖先前的 ID。
+
+<!-- unsupported block: 34 -->
+
+**该方法不会上传登录事件**
+
+#### 3.2 发送事件
+
+您可以调用 `track` 来上传事件，建议您根据先前梳理的埋点文档来设置事件的属性以及发送信息的条件，此处以用户购买某商品作为范例:
+
+```
+Dictionary<string, object> dic = new Dictionary<string, object>();
+dic.Add("channel", "ta");//字符串
+dic.Add("id", 618834);//数字
+dic.Add("isSuccess", true);//布尔
+dic.Add("create_date", Convert.ToDateTime("2019-7-8 20:23:22"));//时间
+List<string> arr = new List<string>();
+arr.Add("value");
+dic.Add("arr", arr);//数组
+TDAnalytics.Track("product_buy", dic);
+```
+
+- 事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。
+- 事件的属性为Dictionary类型
+- Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感，AE 会统一转化为小写字母
+- Value 为该属性的值，支持字符串、数字、布尔、时间、对象
+<!-- unsupported block: 34 -->
+
+**用户属性的要求与事件属性保持一致**
+
+#### 3.3 设置用户属性
+
+对于一般的用户属性，您可以调用 `UserSet`来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：
+
+```
+TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
+```
+
+### 四、最佳实践
+
+以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:
+
+```
+using ThinkingData.Analytics;
+//初始化SDK
+TDAnalytics.Init(APPID,SERVER_URL)
+//如果用户已登录，可以设置用户的账号ID作为身份唯一标识
+TDAnalytics.Login("TA");
+//发送事件
+Dictionary<string, Object> dic = new Dictionary<string, object>();
+dic.Add("channel", "ta");//字符串
+dic.Add("id", 618834);//数字
+dic.Add("isSuccess", true);//布尔
+dic.Add("create_date", Convert.ToDateTime("2019-7-8 20:23:22"));//时间
+List<string> arr = new List<string>();
+arr.Add("value");
+dic.Add("arr", arr);//数组
+TDAnalytics.Track("product_buy", dic);
+// 复杂数据对象
+Dictionary<string, object> json = new Dictionary<string, object>();
+json.Add("key", "value");
+dic.Add("object", json);
+// 复杂数据对象组
+List<Dictionary<string, object>> arr1 = new List<Dictionary<string, object>>();
+Dictionary<string, object> json1 = new Dictionary<string, object>();
+json1.Add("key", "value");
+arr1.Add(json1);
+dic.Add("objects", arr1);
+//设置用户属性
+TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
+```