目录
此内容是否有帮助?

# Unity SDK 使用指南

提示

在接入前, 请先阅读接入前准备。

您可以在 GitHub (opens new window) 获取 Unity SDK 源码。

Unity SDK 支持平台： iOS、Android、Unity Editor、Windows、Mac、WebGL、Switch

最低兼容 Unity 5.4.0 版本，大小约为 320 KB

最新版本为: v2.4.0

更新时间为: 2022-06-14

下载地址 (opens new window)

Unity SDK v2.0.0 与历史版本有较大变化，修改了自动采集的策略，删除了延迟上报逻辑。如果您目前使用的是历史版本，请参考历史版本 Unity SDK 使用指南

# 一、初始化 SDK

# 1.1 集成 SDK

  1. 下载 Unity SDK (opens new window) 资源文件，并导入资源文件到您的项目中：Assets > Import Package > Custom Package，选中您刚刚下载的文件
  2. 添加 ThinkingAnalytics 预置体，并设置 SDK 配置

上图中的配置分别为：

Configuration

  • Start Manually：是否开启手动初始化。若开启，则需要调用StartThinkingAnalytics手动初始化 SDK；若不开启，则会在 ThinkingAnalytics 预置体加载时自动初始化 SDK。参考“手动初始化 TA 实例”。
  • Enable Log：是否开启日志。若开启，则会打印上报情况，以方便您的调试。您也可以在 Editor 模式下，检验事件上报是否正确，对于不符合条件的属性，会以 warning 日志显示在控制台中。
  • Network Type：设置上报数据到服务器的网络条件，默认为 DEFAULT，以下是所有可选项及对应说明：
    • DEFAULT：2G, 3G, 4G, 5G 及 WIFI 环境下上报数据
    • WIFI：只在 WIFI 环境下上报数据
    • ALL：2G, 3G, 4G, 5G 及 WIFI 环境下上报数据

Tokens

每一个 Token 标识一个实例。如需向多个项目上报数据，可点击右下角 “+” 号增加项目配置，多项目的注意事项请参考节末的“多项目支持”一节，您可以添加拥有不同的 APP ID 的多个 Token 配置。

  • APP ID: 需要进行配置，您的项目的 APP_ID，在您申请项目时会给出，请在此处填入。
  • SERVER URL: 需要进行配置，为数据接收端的 URL：
    • 如果您使用的是云服务，请输入以下 URL:
      • https://global-receiver-ta.thinkingdata.cn
    • 如果您使用的是私有化部署的版本，请输入以下 URL:
      • https://数据采集地址
  • MODE: SDK 实例运行模式，生成环境请务必使用 NORMAL 模式。详情请参考 SDK 模式。
  • TimeZone: 自 v1.4.3 开始支持，数据默认的对齐时区。如果您指定了对齐时区，那么数据的时间以及属性中的 DateTime 类型都将按照您指定的时区来对齐。

注意：由于一些设备默认禁止明文传输，因此强烈建议您使用 HTTPS 格式的接收端地址。

# 手动初始化 TA 实例

  • 已加载 ThinkingAnalytics 预置体
// 手动初始化（已加载 ThinkingAnalytics 预置体）
ThinkingAnalyticsAPI.StartThinkingAnalytics();
  • 动态挂载 ThinkingAnalyticsAPI 脚本
// 手动初始化（动态挂载 ThinkingAnalyticsAPI 脚本）
new GameObject("ThinkingAnalytics", typeof(ThinkingAnalyticsAPI));

// 设置实例参数
string appId = "YOUR_APP_ID";
string serverUrl = "YOUR_SERVER_ID";
ThinkingAnalyticsAPI.StartThinkingAnalytics(appId, serverUrl);

// 个性化设置实例参数
string appId = "YOUR_APP_ID";
string serverUrl = "YOUR_SERVER_ID";
ThinkingAnalyticsAPI.TAMode mode = ThinkingAnalyticsAPI.TAMode.NORMAL;
ThinkingAnalyticsAPI.TATimeZone timeZone = ThinkingAnalyticsAPI.TATimeZone.Local;
ThinkingAnalyticsAPI.Token token = new ThinkingAnalyticsAPI.Token(appId, serverUrl, mode, timeZone);
ThinkingAnalyticsAPI.StartThinkingAnalytics(token);

// 多项目实例初始化
string appId_2 = "YOUR_APP_ID_2";
string serverUrl_2 = "YOUR_SERVER_ID_2";
ThinkingAnalyticsAPI.TAMode mode_2 = ThinkingAnalyticsAPI.TAMode.NORMAL;
ThinkingAnalyticsAPI.TATimeZone timeZone_2 = ThinkingAnalyticsAPI.TATimeZone.Local;
ThinkingAnalyticsAPI.Token token_2 = new ThinkingAnalyticsAPI.Token(appId_2, serverUrl_2, mode_2, timeZone_2);

ThinkingAnalyticsAPI.Token[] tokens = new ThinkingAnalyticsAPI.Token[2];
tokens[0] = token;
tokens[1] = token_2;
ThinkingAnalyticsAPI.StartThinkingAnalytics(tokens);

# 多项目支持

在配置 SDK 时，可以添加多个 APP ID，之后在调用 API 时，最后附加一个参数指定 APP ID，以 Identify() 接口为例：

// 为 APP ID 为 “debug-appid” 的APP ID实例设置访客 ID
ThinkingAnalyticsAPI.Identify("unity_debug_id", "debug-appid");

注意：访客 ID、账户 ID、公共属性等在多项目中不共享，需要为每个 APP ID 实例单独进行设置。

如果没有附加 APP ID 参数，则默认使用列表中第一个 APP ID 实例（Token ID 后有 default 标识的实例）。您可以通过拖动列表项的方式调整列表顺序，以此调节默认的 APP ID 实例。

您也可以调用 setDefaultAppid 来修改您的默认 APP ID，如下：

// 设置其他 APP ID 为默认项目 ID
ThinkingAnalyticsAPI.setDefaultAppid("debug-appid-2");
// 调用 track 事件，此时如未传入具体 APP ID，会默认把事件数据上报到<debug-appid-2>项目
ThinkingAnalyticsAPI.track("test_event");

# 1.2 使用 SDK

当您完成了 SDK 配置后，就可以开始使用 SDK 上传事件了，我们也提供了 Sample 供您参考。

using ThinkingAnalytics;

// 上报测试事件, unity_start 为事件名
ThinkingAnalyticsAPI.Track("unity_start");

# 二、设置用户 ID

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

# 2.1 设置访客 ID（可选）

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

ThinkingAnalyticsAPI.Identify("unity_id");

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

ThinkingAnalyticsAPI.GetDistinctId();

# 2.2 设置与清除账号 ID

在用户进行登录时，可调用 Login 来设置用户的账号 ID，在设置完账号 ID 后，将会以账号 ID 作为用户标识 ID，并且设置的账号 ID 将会在调用 Logout 之前一直保留：

// 设置账号 ID
ThinkingAnalyticsAPI.Login("unity_user");

// 清除账号 ID
ThinkingAnalyticsAPI.Logout();

注意：该方法不会上传用户登录、用户登出等事件。

# 三、上传事件

通过 ThinkingAnalyticsAPI.Track() 可以上报事件及其属性。一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用 TA 后台，我们推荐您先上传几个关键事件。

我们也支持了若干自动采集事件，包括游戏启动、关闭、异常、安装等事件。您可以根据业务需求选择是否开启自动采集事件。

# 3.1 上传事件

建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件。事件名称是 string 类型，只能以字母开头，可包含数字，字母和下划线 “_”，长度最大为 50 个字符，对字母大小写不敏感。

Dictionary<string, object> properties = new Dictionary<string, object>()
    {
        {"KEY_DateTime", DateTime.Now.AddDays(1)},
        {"KEY_STRING", "B1"},
        {"KEY_BOOL", true},
        {"KEY_NUMBER", 50.65}
    };
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties);
  • 事件属性是 Dictionary<string, object> 类型，其中每个元素代表一个属性；
  • 事件属性 Key 为属性名称，为 string 类型，规定只能以字母开头，包含数字，字母和下划线 “_”，长度最大为 50 个字符，对字母大小写不敏感；
  • 属性Value支持字符串、数值、bool、DateTime、List、Dictionary；Dictionary中的值可以为字符串、数值、bool、DateTime、List``<string>；

List中的值可以为字符串和Dictionary

注意：

List 类型在 v1.4.0 之后版本开始支持，其元素都将被转为 string 入库.

Dictionary在v2.2.4之后版本开始支持，需配合TA后台v3.5及后续版本使用

当您调用 Track() 时，SDK 会取系统当前时间作为事件发生的时刻，如果您需要指定事件时间，可以传入 DateTime 类型的参数来设置事件触发时间，v1.3.0 版本开始，SDK 支持根据 DataTimeKind 上传事件的时间偏移（对应预置属性 #zone_offset），但是如果传入的 DateTime 的 Kind 属性为 DataTimeKind.Unspecified，则不会上报时间偏移：

DateTime dateTime = DateTime.Now.AddDays(-1);
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties, dateTime);

自 v1.4.3 开始，您可以配置 SDK 实例的默认时区。如果您配置了非 Local 的时区，则所有的事件时间都会对齐到该时区，您传入的 DateTime 的 Kind 属性将被忽略。

自 v2.0.0 开始，SDK 提供了时间校准接口，允许使用服务器时间对 SDK 时间进行校准，请参考校准时间小节的内容。

注意：尽管事件可以设置触发时间，但是接收端会做如下的限制：只接收相对服务器时间在前 10 天至后 3 天的数据，超过时限的数据将会被视为异常数据，整条数据无法入库。

# 3.2 设置静态公共属性

对于一些重要的属性，譬如玩家的区服和渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性，您可以调用 SetSuperProperties 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

Dictionary<string, object> superProperties = new Dictionary<string, object>()
    {
        {"SERVER", 0},
        {"CHANNEL", "A3"}
    };
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);

公共事件属性将会被保存到缓存中，无需每次启动 APP 时调用。如果调用 SetSuperProperties 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和 Track() 上传的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性。

如果您需要删除某个公共事件属性，可以调用 UnsetSuperProperty() 清除其中一个公共事件属性；如果您想要清空所有公共事件属性，则可以调用 ClearSuperProperties();如果您想要获取所有公共事件属性，可以调用GetSuperProperties;

// 清除属性名为 CHANNEL 的公共属性
ThinkingAnalyticsAPI.UnsetSuperProperty("CHANNEL");

// 清空所有公共属性
ThinkingAnalyticsAPI.ClearSuperProperties();

// 获取所有公共属性
ThinkingAnalyticsAPI.GetSuperProperties();

# 3.3 设置动态公共属性

如果公共属性的值不是常量，您可以通过设置动态公共属性的方式实现。动态公共属性也会加入到所有事件中，在事件上报时会动态获取实际上报值。

设置动态公共属性，需要先新建动态公共属性类并实现 IDynamicSuperProperties 接口，复写 public Dictionary<string, object> GetDynamicSuperProperties() 方法，该方法的返回值即是需要设置的动态公共属性。再调用 SetDynamicSuperProperties 传入动态公共属性对象，样例如下：

// 1.定义动态公共属性实现，此例为设置 UTC 时间的动态公共属性
public class DynamicProp : IDynamicSuperProperties
{
    public Dictionary<string, object> GetDynamicSuperProperties()
    {
        return new Dictionary<string, object>() {
            {"KEY_UTCTime", DateTime.UtcNow}
        };
    }
}

// 2.设置动态公共属性
ThinkingAnalyticsAPI.SetDynamicSuperProperties(new DynamicProp());

注意：如果事件属性出现重名，动态公共属性的优先级大于公共事件属性，小于 Track 中设置的事件属性。

# 3.4 记录事件时长

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

// 调用 TimeEvent 开启对 TIME_EVENT 事件的计时
ThinkingAnalyticsAPI.TimeEvent("TIME_EVENT");

// do some thing...

// 通过 Track 上传 TIME_EVENT 事件时，会在属性中添加 #duration 属性
ThinkingAnalyticsAPI.Track("TIME_EVENT");

# 3.5 立即上报事件

如果需要立即上报缓存的事件，可以调用 Flush() 来上报所有缓存的事件。

// 调用 Flush() 上报缓存事件
ThinkingAnalyticsAPI.Flush();

注意：Flush() 接口在非 iOS / Android 平台上从 v2.3.0 开始生效，在 iOS / Android 平台上从 v1.0.0 开始生效。

# 四、用户属性

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

# 4.1 UserSet

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

ThinkingAnalyticsAPI.UserSet(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", 0},
        {"USER_PROP_STRING", "A3"}
    });

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

# 4.2 UserSetOnce

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

ThinkingAnalyticsAPI.UserSetOnce(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", -50},
        {"USER_PROP_STRING", "A3"}
    });

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

# 4.3 UserAdd

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

ThinkingAnalyticsAPI.UserAdd(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", -100.9},
        {"USER_PROP_NUM2", 10.0}
    });

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

# 4.4 UserUnset

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

// 删除单个用户属性
ThinkingAnalyticsAPI.UserUnset("userPropertyName");

// 删除多个用户属性
List<string> listProps = new List<string>();
listProps.Add("aaa");
listProps.Add("bbb");
listProps.Add("ccc");

ThinkingAnalyticsAPI.UserUnset(listProps);

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

# 4.5 UserDelete

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

ThinkingAnalyticsAPI.UserDelete();

# 4.6 UserAppend

从 v1.4.0 开始，您可以调用 UserAppend 为 List 类型的用户属性追加元素:

List<string> stringList = new List<string>();
stringList.Add("apple");
stringList.Add("ball");
stringList.Add("cat");

// 为属性名为 USER_LIST 的用户属性追加 3 个元素
ThinkingAnalyticsAPI.UserAppend(new Dictionary<string, object>
    {
        {"USER_LIST", stringList }
    });

# 4.7 UserUniqAppend

从 v2.4.0 开始，您可以调用 UserUniqAppend 为 List 类型的用户属性进行去重追加元素:

List<string> stringList = new List<string>();
stringList.Add("ball");
stringList.Add("banana");

// 为属性名为 USER_LIST 的用户属性去重追加 2 个元素，如果已经设置过 4.6 中的 3 个元素，那么服务器将会去除 ball，只保留 banana
ThinkingAnalyticsAPI.UserUniqAppend(new Dictionary<string, object>
    {
        {"USER_LIST", stringList }
    });

# 五、自动采集事件

# 5.1 开启自动采集事件的采集

自 v2.0.0 开始，您可以通过调用 EnableAutoTrack 传入 AUTO_TRACK_EVENTS 来开启指定事件的自动采集功能。

// 自动采集事件类型
[Flags]
public enum AUTO_TRACK_EVENTS
{
    NONE = 0,
    APP_START = 1 << 0,
    APP_END = 1 << 1,
    APP_CRASH = 1 << 4,
    APP_INSTALL = 1 << 5,
    ALL = APP_START | APP_END | APP_INSTALL | APP_CRASH
}

对于自动采集事件的说明如下：

  • APP_START: 当游戏进入前台的时候会触发上报 ta_app_start, 预置属性 #resume_from_background 表示本次启动是否是重新启动。
  • APP_END: 当游戏进入后台的时候会触发上报 ta_app_end, 预置属性 #duration 字段表示此次游戏在前台的持续时长，单位为秒。
  • APP_CRASH: 当出现未捕获异常的时候会触发上报 ta_app_crash, 目前 Android 平台会处理虚拟机的未捕获异常。iOS 平台会处理 Unix 信号异常和 NSException 异常。
  • APP_INSTALL: 当应用首次安装后打开时触发上报 ta_app_install. 不区分是否是卸载重装。该时间只在安装后上报一次，后续更新不会再上报。

您可以通过传入 AUTO_TRACK_EVENTS.ALL 来开启目前支持的所有自动采集事件，也可以根据您项目的需求开启部分自动采集事件。

// 开启全部自动采集事件
ThinkingAnalyticsAPI.EnableAutoTrack(AUTO_TRACK_EVENTS.ALL);

// 开启启动和关闭事件的自动采集
ThinkingAnalyticsAPI.EnableAutoTrack(AUTO_TRACK_EVENTS.APP_START | AUTO_TRACK_EVENTS.APP_END);

注意：如果您需要设置自定义访客 ID，或者公共事件属性，需要在打开自动采集事件之前完成。自动采集事件目前不支持动态公共属性。

关于 APP_CRASH 如果在 iOS 和 Android 平台上只想采集 Objective-C 和 Java 异常，不采集 C# 异常，在 v2.3.1 及以上版本，可以通过在 Resources 目录添加 ta_public_config.xml 来配置开关，如下：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- ThinkingAnalytics disable C# Exception -->
    <bool name="DisableCSharpException">true</bool>
</resources>

# 5.2 设置自动采集事件的自定义属性

自 v2.2.4 开始，您可以通过调用 EnableAutoTrack 开启自动采集的同时，传入需要采集的自定义属性。

// 开启自动采集事件，并设置自定属性
ThinkingAnalyticsAPI.EnableAutoTrack(AUTO_TRACK_EVENTS.ALL, new Dictionary<string, object>() {
    {"custom_key", "custom_value"}
});

也可以调用 SetAutoTrackProperties 来指定特定自动采集事件的自定义属性。

注意：SetAutoTrackProperties 不会开启自动采集事件的采集，需要配合 EnableAutoTrack 方法使用。

// 设置指单个自动采集事件的自定义属性
ThinkingAnalyticsAPI.SetAutoTrackProperties(AUTO_TRACK_EVENTS.APP_START, new Dictionary<string, object>() 
{
    {"start_key", "start_value"}
});

// 设置指多个自动采集事件的自定义属性
ThinkingAnalyticsAPI.SetAutoTrackProperties(AUTO_TRACK_EVENTS.APP_INSTALL | AUTO_TRACK_EVENTS.APP_CRASH, new Dictionary<string, object>() 
{
    {"install_crash_key", "install_crash_value"}
});

// 开启全部自动采集事件
ThinkingAnalyticsAPI.EnableAutoTrack(AUTO_TRACK_EVENTS.ALL);

# 5.3 设置自动采集事件回调

从 v2.4.0 开始，支持设置自动采集事件回调，以实时设置自定义属性，或在对应事件触发时机执行自定义代码。

设置自动采集事件回调，需要先新建类并实现 IAutoTrackEventCallback 接口，复写 public Dictionary<string, object> AutoTrackEventCallback(int type, Dictionary<string, object>properties) 方法，该方法的返回值即是需要设置的动采集事件属性。再调用 EnableAutoTrack 传入自动采集事件回调对象，如下：

// 1.自动采集事件回调实现
public class AutoTrackECB : IAutoTrackEventCallback
{
    public Dictionary<string, object> AutoTrackEventCallback(int type, Dictionary<string, object>properties)
    {
        return new Dictionary<string, object>() 
        {
            {"AutoTrackEventProperty", DateTime.Today}
        };
    }
}

// 2.开启自动采集，并设置事件回调
ThinkingAnalyticsAPI.EnableAutoTrack(AUTO_TRACK_EVENTS.ALL, new AutoTrackECB());

# 六、其他配置选项

# 6.1 获取设备 ID

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

ThinkingAnalyticsAPI.GetDeviceId();

// 以设备ID作为访客ID
// ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());

# 6.2 设置数据上报状态

从 v2.4.0 开始支持设置新的数据上报状态：暂停（PAUSE）、停止（STOP）、缓存入库（SAVE_ONLY）、正常（NORMAL）

  • 暂停数据上报（PAUSE）

您可能希望在一些场景下，暂停 SDK 的数据采集以及上报，比如用户处于测试环境中、或者用户登录了一个测试账号，此时您可以调用下列接口，暂停 SDK 的上报。

您可以通过某一实例（包括主要实例以及轻实例）调用 SetTrackStatus，传入 TA_TRACK_STATUS.PAUSE 来暂停 SDK 的上报，该实例已经设置的 #distinct_id、#account_id、公共属性等将保留；该实例已经采集但还未上报成功的数据将继续尝试上报；后续该实例不能采集以及上报任何新数据、不能设置访客 ID、账户 ID 以及公共属性等，但是可以读取该实例已经设置的公共属性和设备 ID、访客 ID、账号 ID 等信息。

实例的暂停状态将会被保存在本地缓存，直到调用 SetTrackStatus 传入 TA_TRACK_STATUS.NORMAL，SDK 实例将会重新恢复数据采集以及上报，需要注意轻实例因为不进行缓存，因此每次打开应用后，轻实例的暂停状态不会被保留，将重新开启上报。

// 暂停默认实例的上报，已缓存数据和已经设置的信息不被清除
ThinkingAnalyticsAPI.SetTrackStatus(TA_TRACK_STATUS.PAUSE);
  • 停止数据上报（STOP）

在一些特殊场景下，您可能需要完全停止 SDK 的功能，比如在适用 GDPR 的地区，用户选择不提供数据采集权限，则您可以调用如下接口完全关闭 SDK 的功能。

停止数据上报（STOP）与暂停数据上报（PAUSE）的最大区别在于，其将会清空该实例的本地缓存，包括本实例的访客 ID，账号 ID，公共属性，以及未上报的数据队列。之后再关闭该实例的采集和上报功能。

// 停止默认实例的上报, 并清空本地缓存
ThinkingAnalyticsAPI.SetTrackStatus(TA_TRACK_STATUS.STOP);

实例的停止状态也将保存在本地缓存，直到调用SetTrackStatus 传入 TA_TRACK_STATUS.NORMAL，后续可以继续上报，但此时相当于一个全新的实例。

  • 缓存数据入库（SAVE_ONLY）

在一些特殊场景下，您可能需要只采集数据，不发送网络请求上报的功能，比如在即时对战游戏中，对战时对网络要求比较高，则您可以调用如下接口，只采集数据入库，而不发送网络请求上报。

直到调用SetTrackStatus 传入TA_TRACK_STATUS.NORMAL，缓存的数据会依次上报到服务器。

// 数据入库，但不上报
ThinkingAnalyticsAPI.SetTrackStatus(TA_TRACK_STATUS.SAVE_ONLY);
  • 正常数据上报（NORMAL）

默认情况下 SDK 正常数据上报不用特别设置，只有在设置过其他三种状态之后，需要恢复正常上报时，才需要调用SetTrackStatus 传入TA_TRACK_STATUS.NORMAL 恢复数据上报。

// 恢复正常数据上报
ThinkingAnalyticsAPI.SetTrackStatus(TA_TRACK_STATUS.NORMAL);

# 6.3 打印数据 Log

在 v2.3.1 及以上版本，未加载 ThinkingAnalytics 预置体时，可以调用 EnableLog 来关闭（默认是开启的）：

// 关闭打印数据Log
ThinkingAnalyticsAPI.EnableLog(false);

// 开启打印数据Log
// ThinkingAnalyticsAPI.EnableLog(true);

# 6.4 创建轻实例

您可以通过轻实例的方式，创建同一个 APP ID 下的多个实例

// 创建轻实例，返回轻实例的 token （类似于 APP ID）
string lightToken = ThinkingAnalyticsAPI.CreateLightInstance();

// 为轻实例设置账号 ID
ThinkingAnalyticsAPI.Login("anotherAccount", lightToken);

// 通过轻实例上报事件
ThinkingAnalyticsAPI.Track("TEST_EVENT", lightToken);

注意：子轻量实例与父实例的 APP ID、上报地址以及部分设置一致，但其他信息不共享

# 6.5 SDK 运行模式

自 v1.4.0 版本开始，SDK 支持在三种模式下运行：

  • NORMAL: 普通模式，数据会存入缓存，并依据一定的缓存策略上报
  • DEBUG: Debug 模式，数据逐条上报。当出现问题时会以日志和异常的方式提示用户
  • DEBUG_ONLY: Debug Only 模式，只对数据做校验，不会入库

注意: DEBUG 模式仅仅用于集成阶段数据校验，不要在生产模式下使用。

为了避免 Debug 模式在生产环境上线，规定只有指定的设备才能开启 Debug 模式。只有在客户端开启了 Debug 模式，并且设备 ID 在 TA 后台的“埋点管理”页的“Debug 数据”板块中配置了的设备才能开启 Debug 模式。

设备 ID 可以通过以下三种方式获取：

  • TA 平台中事件数据中的 #device_id 属性
  • 客户端日志：SDK 初始化完成后会打印设备 DeviceId
  • 通过实例接口调用：获取设备 ID

# 6.6 校准时间

SDK 默认会使用本机时间作为事件发生时间上报，如果用户手动修改设备时间会影响到您的业务分析，自 v2.0.0 版本开始，您可以使用从服务端获取的当前时间戳对 SDK 的时间进行校准。此后，所有未指定时间的调用，包括事件数据和用户属性设置操作，都会使用校准后的时间作为发生时间。

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

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

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

注意：

  • 您需要谨慎地选择您的 NTP 服务器地址，以保证网络状况良好的情况下，用户设备可以很快的获取到服务器时间。
  • 使用 NTP 服务进行时间校准存在一定的不确定性，建议您优先考虑用时间戳校准的方式。

除了以上校准时间接口外，在 v2.0.0 提供了所有用户属性接口的时间函数重载，您可以在调用用户属性相关接口时，传入 DateTime 对象，则系统会使用传入的 DateTime 对象来设定数据的 #time 字段。

# 七、相关预置属性

# 7.1 预置属性说明

各个平台采集的预制属性会有一定的差异，具体可以参考如下文档: Android平台 、 iOS平台

非Native平台的预制属性:

属性名
 中文名
 说明
#ip
 IP
地址
 用户的
IP
地址，TA 将以此获取用户的地理位置信息
#country
 国家
 用户所在国家，根据
IP
地址生成
#country_code
 国家代码
 用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据
IP
地址生成
#province
 省份
 用户所在省份，根据
IP
地址生成
#city
 城市
 用户所在城市，根据
IP
地址生成
#os_version
 操作系统版本
 如windows10
#manufacturer
 设备制造商
 显卡的厂商名称
#os
 操作系统
 如 MacOS,
Windows等
#device_id
 设备 ID
 用户的设备 ID
#screen_height
 屏幕高度
 用户设备的屏幕高度，如 1920 等
#screen_width
 屏幕宽度
 用户设备的屏幕高度，如 1080 等
#device_model
 设备型号
 用户设备的型号，如 iPhone 8 等
#app_version
 APP 版本
 您的 APP 的版本
#bundle_id
 应用唯一标识
 应用包名
#lib
 SDK
类型
 您接入
SDK
的类型，如 Android，iOS 等
#lib_version
 SDK
版本
 您接入
SDK
的版本
#network_type
 网络状态
 上传事件时的网络状态，如
Mobile,LAN
#zone_offset
 时区偏移
 数据时间相对 UTC 时间的偏移小时数

# 7.2 获取预置属性

v2.2.0 及以后的版本可以调用 ThinkingAnalyticsAPI.GetPresetProperties() 方法获取预置属性。

服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取 App 端的预置属性，再传给服务端。

//获取属性对象
TDPresetProperties presetProperties = ThinkingAnalyticsAPI.GetPresetProperties();

//生成事件预置属性
Dictionary<string, object> eventPresetProperties = presetProperties.ToEventPresetProperties();
/*
   {
	"#carrier": "中国电信",
	"#os": "iOS",
	"#device_id": "A8B1C00B-A6AC-4856-8538-0FBC642C1BAD",
	"#screen_height": 2264,
	"#bundle_id": "com.sw.thinkingdatademo",
 	"#app_version": "0.1",
	"#manufacturer": "Apple",
	"#device_model": "iPhone7",
	"#screen_width": 1080,
	"#system_language": "zh",
	"#os_version": "10",
	"#network_type": "WIFI",
	"#zone_offset": 8,
        "#app_version":"1.0.0"
    }
*/

//获取某个预置属性
string bundleId = presetProperties.BundleId;//包名
string appVersion = presetProperties.AppVersion;//App版本号
string os = presetProperties.OS;//os类型，如Android、iOS
string systemLanguage = presetProperties.SystemLanguage;//手机系统语言类型
int screenWidth = presetProperties.ScreenWidth;//屏幕宽度
int screenHeight = presetProperties.ScreenHeight;//屏幕高度
string deviceModel = presetProperties.DeviceModel;//设备型号
string deviceId = presetProperties.DeviceId;//设备唯一标识
string carrier = presetProperties.Carrier;//手机SIM卡运营商信息，双卡双待时，取主卡的运营商信息
string manufacture = presetProperties.Manufacturer;//手机制造商 如HuaWei、Apple
string networkType = presetProperties.NetworkType;//网络类型
string osVersion = presetProperties.OSVersion;//系统版本号
double zoneOffset = presetProperties.ZoneOffset;//时区偏移值
string appVersion = presetProperties.appVersion;//App版本号

IP，国家城市信息由服务端解析生成，客户端不提供接口获取这些属性

# 7.3 预制属性开关

在 v2.3.1 及以上版本，支持屏蔽指定预制属性的上报。

通过在 Resources 目录添加 ta_public_config.xml 来配置开关，配置的字段对应的预置属性将不会上传。如下：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- ThinkingAnalytics DisablePresetProperties start -->
    <string-array name="TDDisPresetProperties">
       <item>#disk</item>
       <item>#fps</item>
       <item>#ram</item>
       <!-- <item>#app_version</item> -->
       <!-- <item>#os_version</item> -->
       <!-- <item>#manufacturer</item> -->
       <!-- <item>#device_model</item> -->
       <!-- <item>#screen_height</item> -->
       <!-- <item>#screen_width</item> -->
       <!-- <item>#carrier</item> -->
       <!-- <item>#device_id</item> -->
       <!-- <item>#system_language</item> -->
       <!-- <item>#lib</item> -->
       <!-- <item>#lib_version</item> -->
       <!-- <item>#os</item> -->
       <!-- <item>#bundle_id</item> -->
       <!-- <item>#install_time</item> -->
       <!-- <item>#start_reason</item> -->
       <!-- <item>#simulator</item> -->
       <!-- <item>#network_type</item> -->
       <!-- <item>#start_reason</item> -->
       <!-- <item>#resume_from_background</item> -->
       <!-- <item>#title</item> -->
       <!-- <item>#screen_name</item> -->
       <!-- <item>#url</item> -->
       <!-- <item>#referrer</item> -->
       <!-- <item>#element_type</item> -->
       <!-- <item>#element_id</item> -->
       <!-- <item>#element_position</item> -->
       <!-- <item>#element_content</item> -->
       <!-- <item>#element_selector</item> -->
       <!-- <item>#app_crashed_reason</item> -->
    </string-array>
    <!-- ThinkingAnalytics DisablePresetProperties end -->
</resources>

# 八、进阶功能

从 v2.1.0 开始，Unity SDK 支持上报三种特殊类型事件: 首次事件、可更新事件、可重写事件。这三种事件需要配合 TA 系统 2.8 及之后的版本使用。由于特殊事件只在某些特定场景下适用，所以请在数数科技的客户成功和分析师的帮助下使用特殊事件上报数据。

# 8.1 首次事件

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

// 示例：上报设备首次事件, 假设事件名为 DEVICE_FIRST
Dictionary<string, object> properties = new Dictionary<string, object>()
{
    {"KEY_STRING", "B1"},
    {"KEY_BOOL", true},
    {"KEY_NUMBER", 50.65},
};

ThinkingAnalyticsAPI.Track(new TDFirstEvent("DEVICE_FIRST", properties));

如果您希望以设备以外的其他维度来判断是否首次，则可以为首次事件设置 FIRST_CHECK_ID. 例如您需要记录某个账号的首次事件，可以将账号 ID 设置为首次事件的 FIRST_CHECK_ID:

// 示例：上报用户账号的首次事件, 假设事件名为 USER_FIRST
TDFirstEvent firstEvent = new TDFirstEvent("USER_FIRST", properties);
firstEvent.SetFirstCheckId("YOUR_ACCOUNT_ID");

ThinkingAnalyticsAPI.Track(firstEvent);

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

# 8.2 可更新事件

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

// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
TDUpdatableEvent updatableEvent = new TDUpdatableEvent("UPDATABLE_EVENT", new Dictionary<string, object>{
    {"status", 3},
    {"price", 100}
}, "test_event_id");

// 上报后事件属性 status 为 3, price 为 100
ThinkingAnalyticsAPI.Track(updatableEvent);


TDUpdatableEvent updatableEvent_new = new TDUpdatableEvent("UPDATABLE_EVENT", new Dictionary<string, object>{
    {"status", 5}
}, "test_event_id");

// 上报后事件属性 status 被更新为 5, price 不变
ThinkingAnalyticsAPI.Track(updatableEvent_new);

可更新事件默认会使用设备当前时间更新历史数据的事件时间，如果您希望指定事件时间，可以在上报可更新事件的时候，指定事件时间：

TDUpdatableEvent updatableEvent = new TDUpdatableEvent("UPDATABLE_EVENT", properties_new, "test_event_id");

// 指定可更新事件的事件时间
updatableEvent.EventTime = DateTime.Now;

# 8.3 可重写事件

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

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITABLE_EVENT
TDOverWritableEvent overWritableEvent = new TDOverWritableEvent("OVERWRITABLE_EVENT", new Dictionary<string, object>{
    {"status", 3},
    {"price", 100}
}, "test_event_id");

// 上报后事件属性 status 为 3, price 为 100
ThinkingAnalyticsAPI.Track(overWritableEvent);

TDOverWritableEvent overWritableEvent_new = new TDOverWritableEvent("OVERWRITABLE_EVENT", new Dictionary<string, object>{
    {"status", 5}
}, "test_event_id");

// 上报后事件属性 status 被更新为 5, price 属性被删除
ThinkingAnalyticsAPI.Track(overWritableEvent_new);

可重写事件默认会使用设备当前时间重写历史数据的事件时间，如果您希望指定事件时间，可以在上报可重写事件的时候，指定事件时间：

TDOverWritableEvent overWritableEvent = new TDOverWritableEvent("OVERWRITABLE_EVENT", new Dictionary<string, object>{
    {"status", 3},
    {"price", 100}
}, "test_event_id");

// 指定可重写事件的事件时间
overWritableEvent.EventTime = DateTime.Now;

# 九、加密功能

从 v2.4.0 版本开始，SDK 支持 iOS / Android 加密功能，客户端支持 AES + RSA 对数据进行加密，再由服务端对数据进行解密，加解密能力需要客户端和服务端配合完成，具体请咨询客户成功人员。

分别设置 Token 对象的 enableEncrypt 属性为 true，并设置默认版本号和公钥。

string appId = "YOUR_APP_ID";
string serverUrl = "YOUR_SERVER_URL";
ThinkingAnalyticsAPI.TAMode mode = ThinkingAnalyticsAPI.TAMode.NORMAL;
ThinkingAnalyticsAPI.TATimeZone timeZone = ThinkingAnalyticsAPI.TATimeZone.Local;
ThinkingAnalyticsAPI.Token token = new ThinkingAnalyticsAPI.Token(appId, serverUrl, mode, timeZone);
// 开启加密传输（仅支持iOS/Android）
token.enableEncrypt = true;
// 设置默认版本号、公钥
token.encryptVersion = 0;
token.encryptPublicKey = "YOUR_ENCRYPT_PUBLIC_KEY";
ThinkingAnalyticsAPI.StartThinkingAnalytics(token);

# ChangeLog

# v2.4.0 2022/06/14

  • 新增支持去重追加用户属性
  • 新增支持自动采集事件回调
  • 新增支持 iOS / Android 数据加密上报
  • 优化代码

# v2.3.1 2022/04/21

  • 新增预置属性禁用开关
  • 优化代码

# v2.3.0 2022/02/28

  • 全平台支持缓存事件、批量发送
  • 优化代码

# v2.2.5 2022/01/17

  • 新增预置属性#app_version
  • 支持 Switch 等平台，放开对支持平台的限制
  • 简化初始化流程，放开 Unity 预置体的限制
  • 优化代码

# v2.2.4 2021/11/15

  • 支持复杂数据类型
  • 自动采集事件支持自定义属性
  • 支持 WebGL
  • 优化代码

注意：若从低版本升级到 v2.2.4，或手动初始化且未加载 ThinkingAnalytics 预置体，需注意有两个脚本要挂载到 GameObject 上：ThinkingAnalyticsAPI 、 ThinkingSDKTask 。

# v2.2.2 2021/09/15

  • 支持手动初始化
  • 支持事件黑名单
  • 优化代码

# v2.2.1 2021/07/21

  • 优化代码

# v2.2.0 2021/06/16

  • 支持预置属性获取
  • 新增 C# 异常采集
  • 兼容Bitcode
  • 优化对低版本Unity的支持
  • 更新 Android SDK (v2.7.0)、iOS SDK (v2.7.0)
  • 代码优化

# v2.1.5 2021/04/19

  • 兼容低版本.net
  • 代码优化

# v2.1.4 2021/03/15

  • 适配iOS 14
  • 适配Android 11
  • 新增预置属性#bundle_id(应用唯一标识)
  • 优化网络信号获取逻辑

# v2.1.3 2021/01/04

  • 支持UnityEditor中上报数据
  • 支持PC端游戏(Windows,MacOS)
  • 多实例场景,支持代码设置默认实例

# v2.1.2 2020/10/29

  • 适配 iOS 5G 网络
  • 优化 install,start 事件上报逻辑
  • 优化数据传输格式
  • 默认网络上报策略调整为 2G/3G/4G/5G/WIFI

# v2.1.1 2020/08/25

  • 修复特殊事件不设置 timeZone 导致上报错误的#zone_offset 的问题.

# v2.1.0 2020/08/24

  • 支持首次事件, 允许传入自定义的 ID 校验是否首次上报
  • 支持可更新、可重写的事件
  • 优化#lib/#lib_version 字段为 Unity SDK 信息
  • 升级原生 SDK 版本为 v2.6.0

# v2.0.8 2020/06/28

  • 更新原生 Android SDK，避免极端情况下的空指针异常

# v2.0.7 2020/06/23

  • 新增预置属性 #system_language
  • 更新原生 SDK 版本号: Android v2.5.5, iOS v2.5.5
  • Android 不再通过修改 gradle 配置来引入 ThinkingAnalyticsSDK 依赖

# v2.0.6 2020/06/17

  • 解决 iOS 32 位机型 long 型溢出的问题

# v2.0.5 2020/05/19

  • 解决 2018.04 版本无法使用 ntp 校准时间的问题

# v2.0.4 2020/05/15

  • 更新原生 iOS SDK 到 v2.5.2，解决上个版本中 Debug 模式问题

# v2.0.3 2020/05/14

  • 更新原生 SDK 版本，适配 TA 后台埋点管理功能
  • 优化代码，避免出现异常（可能会导致与其他崩溃采集 SDK 冲突）

# v2.0.2 2020/04/17

  • 修复 Double 类型在自定义 CultureInfo 的场景下格式错误

# v2.0.1 2020/04/14

  • 修复 Android 平台 DEBUG 模式上报事件的 BUG

# v2.0.0 2020/04/03

  • 修改自动采集逻辑，支持四种类型的自动采集事件：启动、关闭、崩溃、安装
  • 支持 SDK 时间校准功能，支持时间戳校准和 NTP 服务器校准
  • 允许为用户属性相关设置接口传入指定时间

# v1.4.3 2020/03/19

  • 支持对数据 #time 属性的默认时区设置
  • 更新原生 SDK 版本

# v1.4.2 2020/02/21

  • 更新 iOS 插件，修复在较老版本 iOS 系统中引入的 bug

# v1.4.1 2020/02/14

  • 适配 Unity 2019.3.1f1

# v1.4.0 2020/02/11

  • 属性值支持 List / Array 类型
  • 新增 UserAppend 接口
  • 支持 Debug 模式数据校验
  • 支持为每个实例单独配置接收端地址
  • 去除本地数据格式校验

# v1.3.1 2019/12/25

  • 修复 Android 4.3 以下版本退出超时
  • 修复 未包含 iOS 开发环境时的报错

# v1.2.0 2019/09/02

  • 支持关闭/打开数据上报
  • 支持暂停/继续数据上报
  • 支持轻量级实例
  • 修复 2019.2.1f 版本设置网络类型失败
  • 修复 timeEvent 不准确问题
  • Android/iOS SDK 升级为 2.1.0

# v1.1.0 2019/08/09

  • 支持获取设备 ID
  • 支持动态公共属性
  • 支持安装事件采集
  • 内嵌 Android SDK 升级为 2.0.2
  • 内嵌 iOS SDK 升级为 2.0.1
  • 支持上报缓存选项，用户可以选择主动调用 StartTrack() 去开始上报

# v1.0.0 2019/06/20

  • 支持 访客 ID 和 用户账号 的设置
  • 支持事件和用户属性上报
  • 支持 ta_app_start 和 ta_app_end 事件的自动上报
  • 支持公共属性接口
  • 支持 timeEvent 接口
  • 支持多项目上报