历史版本 Unity SDK 使用指南

Unity SDK 已经升级至 v2.0.0，本文为历史版本的使用指南。如果您需要新接入，请参考最新的 Unity SDK 使用指南

本指南将会介绍如何使用 Unity SDK 接入您的项目。建议在接入开始前，先阅读数据规则一章。您可以在访问 GitHub 获取 Unity SDK 的源代码。

最新版本为: v1.4.4

更新时间为: 2020-04-17

下载地址

1. 初始化 SDK

1.1 集成 SDK

下载 Unity SDK 资源文件，并导入资源文件到您的项目中：Assets > Import Package > Custom Package，选中您刚刚下载的文件

注意：Android 插件使用 Gradle 集成，因此目前只支持 Unity 5.4 之后的版本。
添加 ThinkingAnalytics GameObject，并设置 SDK 配置

上图中的配置分别为：

Configuration

Enable Log：是否开启日志，若开启，则会打印上报情况，以方便您的调试。您也可以在 Editor 模式下，检验事件上报是否正确，对于不符合条件的属性，会以 warning 日志显示在控制台中。
Network Type：设置上报数据到服务器的网络条件，默认为 DEFAULT，以下是所有可选项及对应说明：
- DEFAULT：3G, 4G, 5G 及 WIFI环境下上报数据
- WIFI：只在 WIFI 环境下上报数据
- ALL：2G, 3G, 4G, 5G 及 WIFI环境下上报数据
Postpone Track：设置是否延迟上报，开启该选项后，数据将会在调用 StartTrack() 后才开始上报，调用前数据将会被缓存，直到 StartTrack() 被调用。如果您需要设置访客 ID 或者公共属性，建议您开启此项，调用请参考延迟上报部分

Tokens

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

APP ID: 需要进行配置，您的项目的 APP_ID，在您申请项目时会给出，请在此处填入。
SERVER URL: 需要进行配置，为数据接收端的 URL：
- 如果您使用的是云服务，请输入以下 URL:
  - https://receiver.ta.thinkingdata.cn
- 如果您使用的是私有化部署的版本，请输入以下 URL:
  - https://数据采集地址
MODE: SDK 实例运行模式，生成环境请务必使用 NORMAL 模式。详情请参考 SDK 模式。
Auto Track：是否开启自动采集事件，如果勾选了，则 SDK 会自动记录游戏的启动以及关闭，详情请参考自动采集事件
TimeZone: 自 v1.4.3 开始支持，数据默认的对齐时区。该设置目前只针对事件时间和用户属性设置的时间生效，对属性中的 DateTime 类型不生效。

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

多项目支持

在配置 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 实例。

1.2 使用 SDK

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

using ThinkingAnalytics;

ThinkingAnalyticsAPI.Track("unity_start");

2. 设置用户 ID

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

a) 设置访客 ID（可选）

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

ThinkingAnalyticsAPI.Identify("unity_id");

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

ThinkingAnalyticsAPI.GetDistinctId();

b) 设置与清除账号 ID

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

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

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

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

3. 上传事件

通过 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 个字符，对字母大小写不敏感；
属性值支持五种类型：字符串、数值类、bool、DateTime、List 类型。

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

当您调用 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 属性将被忽略。

注意：尽管事件可以设置触发时间，但是接收端会做如下的限制：只接收相对服务器时间在前 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().

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

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

3.3 设置动态公共属性

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

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

using ThinkingAnalytics;

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

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");

4. 用户属性

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"}
    });

与事件属性类似：

用户属性是 Dictionary<string, object> 类型，其中每个元素代表一个属性；
用户属性 Key 为属性名称，为 string 类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感；
用户属性值支持四种类型：字符串、数值类、bool、DateTime、List.

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

4.2 UserSetOnce

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

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

注意：UserSetOnce设置的用户属性类型及限制条件与 UserSet 一致。

4.3 UserAdd

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

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

注意： UserAdd 中的属性类型以及 Key 值的限制与 UserSet 一致，但 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);

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 }
    });

5. 自动采集事件

如果在配置 SDK 时，勾选了Auto Track 选项，SDK 会自动记录：

ta_app_start，即游戏启动事件，每次用户获得焦点（即在游戏中）触发
ta_app_end，游戏关闭事件，当游戏进入Pause状态时触发，会附加#duration属性，记录本次游戏时长（单位是秒）

1.1.0 版本开始，可以通过接口调用的方式采集安装事件：

// 采集 APP 安装事件
ThinkingAnalyticsAPI.TrackAppInstall();

ta_app_install，游戏安装事件，安装事件只会在用户在安装后首次打开APP时启动，用户升级APP不会触发，用户删除后重装APP会再次触发该事件。

6. 其他配置选项

6.1 获取设备ID

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

ThinkingAnalyticsAPI.GetDeviceId();

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

6.2 延迟上报

如果您勾选了 Postpone Track 选项，意味着所有的上报请求（包括用户属性设置和事件追踪）都会先被缓存，直到您主动调用以下方法:

ThinkingAnalyticsAPI.StartTrack();

当这个接口被调用后，数据才会开始上报，在该接口调用前已产生的数据，在上报时，会重新设置的用户ID并加入公共属性。因此在调用StartTrack()前设置用户ID与公共属性，可以对所有数据都生效，适合需要设置访客ID，公共属性的场景：

//设置访客ID
ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());

//设置公共属性
Dictionary<string, object> superProperties = new Dictionary<string, object>()
    {
        {"SERVER", 0},
        {"CHANNEL", "A3"}
    };
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);

//调用上报启动接口
ThinkingAnalyticsAPI.StartTrack();

6.3 暂停/停止数据上报

在2.1.0版本中，新增了停止SDK上报数据的功能，一共有两类停止SDK上报的接口：

暂停SDK上报（EnableTracking）

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

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

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

// 暂停默认实例的上报，已缓存数据和已经设置的信息不被清除
ThinkingAnalyticsAPI.EnableTracking(false);

// 恢复默认实例的上报
ThinkingAnalyticsAPI.EnableTracking(true);

停止SDK上报（OptOutTracking）

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

OptOutTracking只能通过主要实例调用，与EnableTracking的最大区别在于，其将会清空该实例的本地缓存，包括本实例的访客ID，账号ID，公共属性，以及未上报的数据队列。之后再关闭该实例的采集和上报功能。

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

如果您希望关闭SDK功能的同时，删除该用户在TA集群中的用户数据，可以调用OptOutTrackingAndDeleteUser，这将会在停止SDK实例的功能前，上报一条 UserDelete数据，以删除该用户的用户数据。

// 停止默认实例的上报，并发送 user_del
ThinkingAnalyticsAPI.OptOutTrackingAndDeleteUser();

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

// 重新开启上报
ThinkingAnalyticsAPI.OptInTracking();

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

Release Note

v1.4.4 2020/04/17

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

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 接口
支持多项目上报

历史版本 Unity SDK 使用指南

历史版本 Unity SDK 使用指南

1. 初始化 SDK

1.1 集成 SDK

多项目支持

1.2 使用 SDK

2. 设置用户 ID

a) 设置访客 ID（可选）

b) 设置与清除账号 ID

3. 上传事件

3.1 上传事件

3.2 设置静态公共属性

3.3 设置动态公共属性

3.4 记录事件时长

4. 用户属性

4.1 UserSet

4.2 UserSetOnce

4.3 UserAdd

4.4 UserUnset

4.5 UserDelete

4.6 UserAppend

5. 自动采集事件

6. 其他配置选项

6.1 获取设备ID

6.2 延迟上报

6.3 暂停/停止数据上报

6.4 创建轻实例

6.5 SDK 运行模式

Release Note

v1.4.4 2020/04/17

v1.4.3 2020/03/19

v1.4.2 2020/02/21

v1.4.1 2020/02/14

v1.4.0 2020/02/11

v1.3.1 2019/12/25

v1.2.0 2019/09/02

v1.1.0 2019/08/09

v1.0.0 2019/06/20

results matching ""

No results matching ""