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//346/270/270/346/210/217/345/274/225/346/223/216/unreal//350/277/233/351/230/266/346/214/207/345/215/227//350/207/252/345/212/250/351/207/207/351/233/206.md

@@ -0,0 +1,81 @@
+---
+code: unreal_sdk_autotrack
+name: "自动采集"
+wikiToken: XTgHwViIuiuHbFkPwuYc7vTrnAQ
+parentWikiToken: SpNbwbJcEi1MnPkeumQcK3M8nNg
+updateTime: 1745309715000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=unreal_sdk_autotrack
+---
+# 自动采集
+
+### 一、自动采集事件
+
+TDAnalytics SDK 当前支持三种事件的自动采集：
+
+- ta_app_install: 游戏安装，当安装后首次打开游戏会采集该事件
+- ta_app_start: 游戏进入前台的时候采集该事件
+- ta_app_end: 游戏退到后台的时候采集该事件
+通过调用 `EnableAutoTrack` 接口可以开启自动采集：
+
+```
+// 开启自动采集
+UTDAnalytics::EnableAutoTrack();
+```
+
+<!-- unsupported block: 34 -->
+
+注意： 如果您需要自定义访客 ID，请务必在开启自动采集功能之前调用 Identify 接口设置访客 ID.
+
+也可以手动传入需要开启采集的自动采集事件：
+
+```
+TArray<FString> EventTypeList;
+EventTypeList.Emplace(TEXT("ta_app_install"));
+EventTypeList.Emplace(TEXT("ta_app_start"));
+EventTypeList.Emplace(TEXT("ta_app_end"));
+UTDAnalytics::EnableAutoTrackWithType(EventTypeList, AppID);
+```
+
+### 二、设置自定义属性
+
+v1.4.1版本开始支持为自动采集事件设置自定义属性，当采集指定的事件时，会将自定义属性合并到该事件属性中并上报。
+
+```
+TArray<FString> EventTypeList;
+EventTypeList.Emplace(TEXT("ta_app_install"));
+EventTypeList.Emplace(TEXT("ta_app_start"));
+EventTypeList.Emplace(TEXT("ta_app_end"));
+UTDAnalytics::EnableAutoTrackWithTypeAndProperties(EventTypeList, TEXT("{\"autoTrackKey1\":\"autoTrackvalue1\",\"autoTrackKey2\":\"autoTrackvalue2\"}"), AppID);
+```
+
+### 三、设置自动采集事件回调
+
+V1.5.0版本开始支持为自动采集事件设置回调方法，当采集指定的事件时，会通过该回调通知并回传当前所携带的事件属性，您可以根据需要转发数据，或者增加新的事件属性作为返回。
+
+```
+//定义回调
+FString UTAUserWidget::TAAutoTrackProperties(FString AutoTrackEventType, FString Properties)
+{
+    //AutoTrackEventType 自动采集事件类型
+    //Properties 当前事件携带的事件属性
+    //处理逻辑
+    FDateTime TDateTime = FDateTime::Now();
+    int64 SecondTimestamp = TDateTime.ToUnixTimestamp();
+    int32 MillisecondPart = TDateTime.GetMillisecond();
+    FString TimeStr = *FString::Printf(TEXT("%llu"), SecondTimestamp);
+    TimeStr += *FString::Printf(TEXT("%lld"), MillisecondPart);
+    return "{\"auto_property1_name\":\"" + AutoTrackEventType + "\",\"auto_property2_time\":\"" + TimeStr + "\"}";
+}
+
+//设置回调
+void UTAUserWidget::Call_TA_SetAutoTrackEventListener()
+{   
+    TArray<FString> EventTypeList;
+    EventTypeList.Emplace(TEXT("ta_app_install"));
+    EventTypeList.Emplace(TEXT("ta_app_start"));
+    EventTypeList.Emplace(TEXT("ta_app_end"));
+    UTDAnalytics::SetAutoTrackEventListener(this, &UTAUserWidget::TAAutoTrackProperties, EventTypeList, AppID);
+}
+```
+
+####

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//346/270/270/346/210/217/345/274/225/346/223/216/unreal//350/277/233/351/230/266/346/214/207/345/215/227//351/242/204/347/275/256/345/261/236/346/200/247.md

@@ -0,0 +1,181 @@
+---
+code: unreal_sdk_preset_properties
+name: "预置属性"
+wikiToken: NruMwsdtgiZKdnkp9H0c3CCKnCf
+parentWikiToken: SpNbwbJcEi1MnPkeumQcK3M8nNg
+updateTime: 1745310879000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=unreal_sdk_preset_properties
+---
+# 预置属性
+
+#### 一、 预置属性说明
+
+<!-- unsupported block: 34 -->
+
+各个平台采集的预置属性会有一定的差异，具体可以参考如下文档: Android平台 、 iOS平台  
+
+**非Native平台(PC)的****预置****属性:**
+
+**属性名**
+
+**中文名**
+
+**属性类型**
+
+**说明**
+
+#ip
+
+IP 地址
+
+文本
+
+用户的 IP 地址，AE 将以此获取用户的地理位置信息
+
+#country
+
+国家
+
+文本
+
+用户所在国家，根据 IP 地址生成
+
+#country_code
+
+国家代码
+
+文本
+
+用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成
+
+#province
+
+省份
+
+文本
+
+用户所在省份，根据 IP 地址生成
+
+#city
+
+城市
+
+文本
+
+用户所在城市，根据 IP 地址生成
+
+#os_version
+
+操作系统版本
+
+文本
+
+如windows10
+
+#os
+
+操作系统
+
+文本
+
+如 MacOS,Windows等
+
+#device_id
+
+设备 ID
+
+文本
+
+用户的设备 ID
+
+#screen_height
+
+屏幕高度
+
+数值
+
+用户设备的屏幕高度，如 1920 等
+
+#screen_width
+
+屏幕宽度
+
+数值
+
+用户设备的屏幕高度，如 1080 等
+
+#app_version
+
+APP 版本
+
+文本
+
+您的 APP 的版本
+
+#lib_version
+
+SDK 版本
+
+文本
+
+您接入 SDK 的版本
+
+#zone_offset
+
+时区偏移
+
+数值
+
+数据时间相对 UTC 时间的偏移小时数
+
+#system_language
+
+操作系统语言
+
+文本
+
+用户所使用系统中设置的语言，如 zh
+
+#install_time
+
+安装时间
+
+时间
+
+用户安装应用的时间
+
+#fps
+
+帧率
+
+文本
+
+当前的屏幕帧率
+
+#disk
+
+硬盘状态
+
+文本
+
+当前存储使用情况 "剩余/总空间"
+
+#ram
+
+内存状态
+
+文本
+
+当前内存使用情况 "剩余/总内存"
+
+<!-- unsupported block: 19 -->
+
+3.0.0及之后的版本，底层使用的是C++ SDK，#install_time、#app_version、#os_version、#fps、#ram、#disk预置属性暂时无法采集，如果需要这些预置属性，可以使用3.0.0以前的版本
+
+#### 二、 获取预置属性
+
+在 v1.3.0 版本新增预获取制属性接口, SDK 会在事件属性上报时候自动加上一些内置属性, 您可以通过此接口获取预置属性。
+
+```
+FString PresetProperties = UTDAnalytics::GetPresetProperties();
+```

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//346/270/270/346/210/217/345/274/225/346/223/216/unreal//350/277/233/351/230/266/346/214/207/345/215/227.md

@@ -0,0 +1,346 @@
+---
+code: unreal_sdk_advanced
+name: "进阶指南"
+wikiToken: SpNbwbJcEi1MnPkeumQcK3M8nNg
+parentWikiToken: WzIhwbKmkiwbUDkYZ4hcySdrnrg
+updateTime: 1745310878000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=unreal_sdk_advanced
+---
+# 进阶指南
+
+### 一、设置用户ID
+
+SDK 实例默认会使用随机 UUID 作为每个用户的默认访客 ID，该 ID 将会作为用户在未登录状态下身份识别 ID。需要注意的是，访客 ID 在用户重新安装 App 以及更换设备时将会变更。
+
+#### 1.1 设置访客 ID 
+
+::: tip 提示
+
+ 一般情况下，您不需要自定义访客 ID. 请确保已经理解用户识别规则，再进行访客 ID 的设置。
+
+如果您需要替换访客 ID，则应当在初始化 SDK 结束之后立即进行调用，请勿多次调用，以免产生无用的账号
+
+ :::
+
+如果您的游戏有自己的访客 ID 管理体系，则您可以调用 `SetDistinctId` 来设置访客 ID:
+
+```
+// 将访客ID设置为Thinker
+UTDAnalytics::SetDistinctId("Thinker");
+```
+
+如果需要获得访客 ID，可以调用 `GetDistinctId` 获取：
+
+```
+FString distinctId = UTDAnalytics::GetDistinctId();
+```
+
+#### 1.2 设置账号 ID
+
+在用户进行登录时，可调用 `Login` 来设置用户的账号 ID， AE 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 `Logout` 之前一直保留。多次调用 `Login` 将覆盖先前的账号 ID 。
+
+```
+// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
+UTDAnalytics::Login("TA");
+```
+
+<!-- unsupported block: 34 -->
+
+**该方法不会上传登录事件**
+
+#### 1.3 清除账号 ID
+
+在用户产生登出行为之后，可调用 `Logout` 来清除账号 ID，在下次调用 `Login` 之前，将会以访客 ID 作为身份识别 ID。
+
+```
+UTDAnalytics::Logout();
+```
+
+我们推荐您在显性的登出事件时调用 `Logout`，比如用户产生了注销账号这一行为时才调用，而不需要在关闭游戏时调用。
+
+<!-- unsupported block: 34 -->
+
+**该方法不会上传登出事件**
+
+### 二 、发送事件
+
+在 SDK 初始化完成之后，您就可以进行数据埋点，收集用户的的行为信息。一般情况下普通事件即可满足业务场景需求，您也可以根据自己的实际业务场景使用首次、可更新等事件。
+
+#### 2.1 普通事件
+
+您可以调用 `track` 来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送事件的条件，此处以用户购买某商品作为范例：
+
+```
+TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
+Properties->SetStringField("product_name", "商品名");
+UTDAnalytics::Track("product_buy",Properties);
+```
+
+#### 2.2 首次事件
+
+首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上第一次发生的事件，则可以用首次事件来上报数据。
+
+```
+TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
+Properties->SetStringField("key", "value");
+UTDAnalytics::TrackFirst("device_activation",Properties);
+```
+
+如果您希望以设备以外的其他维度来判断是否首次，则可以为首次事件自定义first_check_id:
+
+```
+TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
+Properties->SetStringField("key", "value");
+UTDAnalytics::TrackFirstWithId("account_activation", Properties,"TA");
+```
+
+<!-- unsupported block: 34 -->
+
+注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 1 小时入库。
+
+#### 2.3 可更新事件
+
+您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。
+
+```
+// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
+// 上报后事件属性 status 为 3, price 为 100
+TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
+Properties->SetNumberField("status",3);
+Properties->SetNumberField("price",100);
+UTDAnalytics::TrackUpdate("UPDATABLE_EVENT", Properties,"test_event_id");
+
+// 上报后事件属性 status 为 5, price 为 100
+TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
+NewProperties->SetNumberField("status",5);
+UTDAnalytics::TrackUpdate("UPDATABLE_EVENT",NewProperties,"test_event_id");
+```
+
+#### 2.4 可重写事件
+
+可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。
+
+```
+// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
+// 上报后事件属性 status 为 3, price 为 100
+TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
+Properties->SetNumberField("status",3);
+Properties->SetNumberField("price",100);
+UTDAnalytics::TrackOverwrite("OVERWRITE_EVENT", Properties,"test_event_id");
+
+// 上报后事件属性 status 为 5, price属性被删除
+TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
+NewProperties->SetNumberField("status",5);
+UTDAnalytics::TrackOverwrite("OVERWRITE_EVENT",NewProperties,"test_event_id")
+```
+
+#### 2.5 公共事件属性
+
+公共事件属性指的就是每个事件都会上传的属性。根据属性更新频率，公共事件属性分为`静态公共事件属性`和`动态公共事件属性`。您可以根据具体的业务场景需求，选择不同的公共事件属性设置方法；我们推荐您在发送事件前，先设置公共事件属性。针对同一事件，当公共事件属性、事件自定义属性、预置属性的Key相同时，我们会按照如下优先级进行赋值:`自定义属性>动态公共事件属性>静态公共事件属性>预置属性`。
+
+##### 2.5.1 静态公共事件属性
+
+静态公共事件属性是低频变化且每个事件都会带有的属性，如用户会员等级。通过`SetSuperProperties`设置静态公共事件属性之后，SDK将会在事件采集时获取设置的公共事件属性作为事件的属性。
+
+```
+TSharedPtr<FJsonObject> SuperProperties = MakeShareable(new FJsonObject);
+SuperProperties->SetNumberField("vip_level",2);
+UTDAnalytics::SetSuperProperties(SuperProperties);
+```
+
+静态公共事件属性将会被保存到缓存中，无需每次启动 App 时调用。如果该属性已存在，重新设置的属性将会覆盖原有属性值;如果之前不存在该属性，则会新建属性。除了属性设置，我们也提供其他API来操作静态公共事件属性，满足日常的业务需求。
+
+```
+//获取所有公共事件属性
+TSharedPtr<FJsonObject> SuperProperties = UTDAnalytics::GetSuperProperties();
+```
+
+##### 2.5.2 设置动态公共属性
+
+ 动态公共事件属性是高频变化且每个事件都会带有的属性，如用户的金币数量。通过 `SetDynamicSuperPropertiesTracker` 设置动态公共属性类之后，SDK 将会在事件采集时自动获取动态公共事件属性，并添加到触发的事件中。
+
+```
+// 定义动态公共属性函数
+static FString TDReturnDyldParams() {
+    return "{\"dyld_property1\":\"value1\",\"dyld_property2\":\"value2\"}";
+}
+// 设置动态公共属性
+void UMyDemoWidget::callSetDynamicSuperPropertiesFunction(){
+    // V1.5.0 之前
+    UTDAnalytics::dynamicPropertiesMap.insert(pair<FString,FString(*)(void)>("inset your appid" ,&TDReturnDyldParams));
+    // V1.5.0 开始
+    UTDAnalytics::SetDynamicSuperProperties(this, &UMyDemoWidget::TDReturnDyldParams, "your appid");
+}
+```
+
+#### 2.6 记录事件时长
+
+如果您需要记录某个事件的持续时长，可以调用 `timeEvent` 来配置您想要计时的事件名称开始计时,，当您上传该事件时，将会自动在您的事件属性中加入 `#duration` 这一属性来表示记录的时长，单位为秒。需要注意的是，同一个事件名只能有一个在计时的任务。
+
+```
+//以下示例，完成用户在某个商品页面停留时长的统计
+//用户进入商品页面，开始计时
+UTDAnalytics::TimeEvent("stay_shop");
+ /**do someting
+    .......
+ **/
+//用户离开商品页面，计时结束，"stay_shop" 这一事件中将会带有表示事件时长的属性#duration
+UTDAnalytics::Track("stay_shop", "");
+```
+
+<!-- unsupported block: 34 -->
+
+注意：Windows/MacOS暂不支持记录事件时长。
+
+### 三、用户属性
+
+ AE 平台支持的用户属性设置API有: `UserSet`、`UserSetOnce`、`UserAdd`、`UserDelete`、`UserUnset`、`UserAppend`、`UserUniqueAppend`。
+
+#### 3.1 UserSet
+
+对于一般的用户属性，您可以调用 `UserSet` 来进行设置。使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：
+
+```
+//此时username为TA
+TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
+Properties->SetStringField("user_name", "TA");
+UTDAnalytics::UserSet(Properties);
+//此时username为TE
+TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
+NewProperties->SetStringField("user_name", "TE");
+UTDAnalytics::UserSet(NewProperties);
+```
+
+#### 3.2 UserSetOnce
+
+如果您要上传的用户属性只要设置一次，则可以调用 `UserSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息，以设置首次付费时间来为例
+
+```
+//first_payment_time为2018-01-01 01:23:45.678
+TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
+Properties->SetStringField("first_payment_time","2018-01-01 01:23:45.678");
+UTDAnalytics::UserSetOnce(Properties);
+//first_payment_time仍然为2018-01-01 01:23:45.678
+TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
+NewProperties->SetStringField("first_payment_time","2018-12-31 01:23:45.678");
+UTDAnalytics::UserSetOnce(NewProperties);
+```
+
+#### 3.3 UserAdd
+
+当您要上传数值型的属性时，您可以调用 `UserAdd` 来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值，等同于相减操作。此处以累计付费金额为例：
+
+```
+//此时total_revenue为30
+TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
+Properties->SetNumberField("total_revenue",30);
+UTDAnalytics::UserAdd(Properties);
+//此时total_revenue为678
+TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
+NewProperties->SetNumberField("total_revenue",648);
+UTDAnalytics::UserAdd(NewProperties);
+```
+
+<!-- unsupported block: 34 -->
+
+设置的属性key为字符串，Value 只允许为数值。
+
+#### 3.4 UserDelete
+
+如果您要删除某个用户，可以调用 `UserDelete` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
+
+```
+UTDAnalytics::UserDelete();
+```
+
+#### 3.5 UserUnset
+
+如果您需要重置用户的某个属性，可以调用 `UserUnset` 将已经设置的属性删除。
+
+```
+UTDAnalytics::UserUnset("userPropertyName");
+```
+
+<!-- unsupported block: 34 -->
+
+UserUnset的传入值为被清空属性的 Key 值。
+
+#### 3.6 UserAppend
+
+您可以调用 UserAppend 为 List 类型的用户属性追加元素。
+
+```
+TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
+TArray< TSharedPtr<FJsonValue> > DataArray;
+DataArray.Add(MakeShareable(new FJsonValueString("apple")));
+DataArray.Add(MakeShareable(new FJsonValueString("ball")));
+Properties->SetArrayField("user_list", DataArray);//数组
+UTDAnalytics::UserAppend(Properties);
+```
+
+#### 3.7 UserUniqueAppend
+
+您可以调用 `UserUniqueAppend` 对 数组类型的用户属性进行追加操作。调用 `UserUniqueAppend` 接口会对追加的用户属性进行去重，`UserAppend` 接口不做去重，用户属性可存在重复。
+
+```
+//此时user_list的属性值为["apple"，"ball"]
+TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
+TArray< TSharedPtr<FJsonValue> > DataArray;
+DataArray.Add(MakeShareable(new FJsonValueString("apple")));
+DataArray.Add(MakeShareable(new FJsonValueString("ball")));
+Properties->SetArrayField("user_list", DataArray);//数组
+UTDAnalytics::UserAppend(Properties);
+
+//此时user_list的属性值为["apple","apple","ball","cube"]
+TSharedPtr<FJsonObject> Properties1 = MakeShareable(new FJsonObject);
+TArray< TSharedPtr<FJsonValue> > DataArray1;
+DataArray1.Add(MakeShareable(new FJsonValueString("apple")));
+DataArray1.Add(MakeShareable(new FJsonValueString("cube")));
+Properties->SetArrayField("user_list", DataArray1);//数组
+UTDAnalytics::UserAppend(Properties1);
+
+//此时user_list的属性值为["apple"，"ball","cube"]
+UTDAnalytics::UserUniqueAppend(Properties1);
+```
+
+### 四、其他功能
+
+#### 4.1 获取设备ID
+
+您可以通过调用 `GetDeviceId` 来获取设备 ID：
+
+```
+FString deviceId = UTDAnalytics::GetDeviceId();
+```
+
+#### 4.2 校准时间
+
+SDK 默认会使用本机时间作为事件发生时间上报，如果用户手动修改设备时间会影响到您的业务分析，此时可以通过校准时间操作保证事件发生时间的准确性。我们提供`时间戳`、`NTP`两种时间校准方式。
+
+- 您可以使用从服务端获取的当前时间戳对 SDK 的时间进行校准。此后，所有未指定时间的调用，包括事件数据和用户属性设置操作，都会使用校准后的时间作为发生时间。
+```
+// 1585633785954 为当前 unix 时间戳，单位为毫秒，对应北京时间 2020-03-31 13:49:45
+UTDAnalytics::CalibrateTime(1585633785954);
+```
+
+- 您也可以设置NTP服务器地址，之后 SDK 会尝试从传入的 NTP 服务地址中获取当前时间，并对 SDK 时间进行校准。如果在默认的超时时间（3 秒）之内，未获取正确的返回结果，后续将使用本地时间上报数据。
+```
+// 使用苹果公司 NTP 服务对时间进行校准
+UTDAnalytics::CalibrateTimeWithNtp("time.apple.com");
+```
+
+<!-- unsupported block: 34 -->
+
+1、使用 NTP 服务进行时间校准存在一定的不确定性，建议您优先考虑用时间戳校准的方式
+
+2、您需要谨慎地选择您的 NTP 服务器地址，以保证网络状况良好的情况下，用户设备可以很快的获取到服务器时间
+
+#### 4.3 立即上报数据
+
+在某些业务场景下，如果您期望数据立即上报到 AE 服务器，可以通过调用`Flush`接口完成
+
+```
+UTDAnalytics::Flush();
+```
+
+###