# 历史版本 Unity SDK 使用指南

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

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

最新版本为: v1.4.4

更新时间为: 2020-04-17

下载地址 (opens new window)

# 一、初始化 SDK

# 1.1 集成 SDK

  1. 下载 Unity SDK (opens new window) 资源文件,并导入资源文件到您的项目中:Assets > Import Package > Custom Package,选中您刚刚下载的文件

注意:Android 插件使用 Gradle 集成,因此目前只支持 Unity 5.4 之后的版本。

  1. 添加 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");

# 二、设置用户 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 个字符,对字母大小写不敏感;
  • 属性值支持五种类型:字符串、数值类、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");

# 四、用户属性

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

# 五、自动采集事件

如果在配置 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.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 上报的接口:

  1. 暂停 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);
  1. 停止 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 接口
  • 支持多项目上报