Unity

提示

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

Unity SDK ：支持 iOS、Android、Unity Editor、Windows、Mac、WebGL、Switch、Xbox、PS4/5等游戏终端，支持微信小游戏、抖音小游戏、OPPO等小游戏平台

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

最新版本: v3.0.6

更新时间: 2024-03-20

资源下载: 源码 (opens new window)、SDK下载 (opens new window)

注意

当前文档适用于 v3.0.0 及以后的版本，历史版本请参考 Unity 接入指南（V2） (opens new window)，SDK下载（v2.6.1） (opens new window)

一、集成SDK

1.1 手动集成

1. 下载 Unity SDK (opens new window) 资源文件
2. 双击ta_unity_sdk.unitypackage文件或者通过Assets > Import Package > Custom Package，导入ta_unity_sdk.unitypackage

1.2 Package Manager 集成

从 v2.4.1 开始，支持 Package Manager 方式自动接入 SDK。

1. 打开 Window - Package Manager 菜单
2. 点击 + ，然后选择 Add package from git URL...
3. 输入 https://github.com/ThinkingDataAnalytics/unity-sdk.git ，然后点击 Add，等待加载完成

二、初始化

推荐使用手动方式初始化SDK，我们也提供预置体自动初始化的方式。

2.1 手动初始化

//初始化方式一
TDAnalytics.Init("APPID","SERVER");
//初始化方式二
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);

2.2 自动初始化

TIP

通过 Package Manager 集成 SDK 仅支持部分配置，请以实际为准。

1. 添加 TDAnalytics 预置体，并设置 SDK 配置

上图中的配置分别为：

Configuration

• Start Manually：是否开启手动初始化
  1. 若开启，则需要手动调用TDAnalytics.Init()初始化SDK。
  2. 若不开启，则会在 TDAnalytics 预置体加载时自动初始化 SDK。
• Enable Log：是否开启日志。若开启，则会打印上报情况，以方便您的调试。您也可以在 Editor 模式下，检验事件上报是否正确，对于不符合条件的属性，会以 warning 日志显示在控制台中。

Configs

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

• APP ID: 需要进行配置，您的项目的 APP_ID，在您申请项目时会给出，请在此处填入。
• SERVER URL: 需要进行配置，为数据接收端的 URL：
  • 如果您使用的是云服务，请输入以下 URL: https://global-receiver-ta.thinkingdata.cn
  • 如果您使用的是私有化部署的版本，请输入以下 URL: https://数据采集地址
• MODE: SDK 实例运行模式，生成环境请务必使用 NORMAL 模式。

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

三、常用功能

在使用常用功能之前，建议你先了解用户识别规则；SDK默认会生成随机数作为访客ID，并持久化存储访客ID在本地；用户未登录之前，会以访客ID作为身份识别ID。注意:访客 ID 在用户重新安装 App 以及更换设备时将会变更。

3.1 设置账号ID

在用户进行登录时，可调用Login 来设置用户的账号 ID， TA 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 Logout 之前一直保留。多次调用 Login: 将覆盖先前的账号 ID 。

// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
TDAnalytics.Login("TA");

该方法不会上传登录事件

3.2 设置公共事件属性

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

Dictionary<string, object> superProperties = new Dictionary<string, object>();
superProperties["channel"] = "ta";//字符串
superProperties["age"] = 1;//数字
superProperties["isSuccess"] = true;//布尔
superProperties["birthday"] = DateTime.Now;//时间
superProperties["object"] = new Dictionary<string, object>(){{ "key", "value"}};//对象
superProperties["object_arr"] = new List<object>() {new Dictionary<string, object>(){{ "key", "value" }}};//对象组
superProperties["arr"] = new List<object>() { "value" };//数组
TDAnalytics.SetSuperProperties(superProperties);//设置公共事件属性

公共事件属性将会被保存到缓存中，无需每次启动 App 时调用。如果调用 setSuperProperties: 设置了先前已设置过的公共事件属性，则会覆盖之前的属性。

• 事件属性是 Dictionary<string, object> 类型，其中每个元素代表一个属性
• Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,TA会统一转化为小写字母
• Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组

事件属性、用户属性的要求与公共事件属性保持一致

3.3 开启自动采集

以下是开启安装、启动、关闭事件的示例代码，如果您想详细了解SDK的自动采集能力，可以查看自动采集功能详细介绍

//开启安装、启动、关闭事件的自动采集
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppInstall | TDAutoTrackEventType.AppStart | TDAutoTrackEventType.AppEnd);

3.4 发送事件

您可以调用 Track 来上传事件，建议您根据先前梳理的埋点文档来设置事件的属性以及发送信息的条件，此处以用户购买某商品作为范例

Dictionary<string, object> properties = new Dictionary<string, object>(){{"product_name", "商品名"}};
TDAnalytics.Track("product_buy", properties);

事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。

3.5 设置用户属性

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

//此时username为TA
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
//此时username为TE
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TE"}});

四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

if (授权隐私政策)
{  // 初始化SDK
   TDAnalytics.Init("APPID", "SERVER");
   //如果用户已登录，可以设置用户的账号ID作为身份唯一标识
   TDAnalytics.Login("TA");
   //设置公共事件属性以后，每个事件都会带有公共事件属性
   Dictionary<string, object> superProperties = new Dictionary<string, object>();
   superProperties["channel"] = "ta";//字符串
   superProperties["age"] = 1;//数字
   superProperties["isSuccess"] = true;//布尔
   superProperties["birthday"] = DateTime.Now;//时间
   superProperties["object"] = new Dictionary<string, object>(){{ "key", "value"}};//对象
   superProperties["object_arr"] = new List<object>() {new Dictionary<string, object>(){{ "key", "value" }}};//对象组
   superProperties["arr"] = new List<object>() { "value" };//数组
   TDAnalytics.SetSuperProperties(superProperties);//设置公共事件属性
   //开启自动采集事件
   TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppInstall | TDAutoTrackEventType.AppStart | TDAutoTrackEventType.AppEnd);
   //发送事件
   Dictionary<string, object> properties = new Dictionary<string, object>(){{"product_name", "商品名")}};
   TDAnalytics.Track("product_buy", properties);
   //设置用户属性
   TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
}