/ta-unity-sdk

ThinkingData SDK for Unity 3D

Primary LanguageObjective-CApache License 2.0Apache-2.0

Thinking Analytics Unity SDK 使用指南

Thinking Analytics Unity SDK 提供了事件和用户属性数据采集相关接口，可以很方便的集成到您的项目中，向 TA 系统上报用户数据。

详细的使用指南请参考 Thinking Analytics 官网的Unity SDK 使用指南。

1. 初始化 SDK

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

1.2 添加 ThinkingAnalytics GameObject, 并配置服务器地址和 APP ID

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

1.3 使用 SDK

当您配置好服务器地址和 APP ID 后，就可以开始使用 ThinkingAnalytics namespace 上传事件了，我们也提供了 Sample 供您参考。

using ThinkingAnalytics;

ThinkingAnalyticsAPI.Track("unity_start");

2 设置用户 ID

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

2.1 设置访客 ID（可选）

如果您的 APP 对每个用户有自己的访客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();

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

3 上传事件

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

3.1 上传事件

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

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

当您调用 Track() 时，SDK 会取系统当前时间作为 #event_time 属性值，如果您需要指定事件时间，可以传入 DateTime:

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

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

v1.3.0+ 版本开始，SDK 支持上传事件的时间偏移（对应预置属性 #zone_offset），但是如果传入的 dateTime 的 Kind 属性为 DataTimeKind.Unspecified，则不会上报时间偏移。

3.2 设置公共属性

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

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

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

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

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

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

如果公共属性的值不是常量，您可以通过设置动态公共属性的方式实现。动态公共属性的优先级大于公共事件属性。设置动态公共属性需要实现 IDynamicSuperProperties 接口。方式如下：

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

3.3 记录事件时长

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

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

// do some thing...

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

4 用户属性

TDA 平台目前支持的用户属性设置接口为UserSet、UserSetOnce、UserAdd、UserDelete。

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。

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 UserDelete

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

ThinkingAnalyticsAPI.UserDelete();

4.5 UserUnset

如果您需要重置用户的某个属性，可以调用UserUnset将已经设置的属性删除。此接口支持传入字符串或者列表类型的参数:

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

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

ThinkingAnalyticsAPI.UserUnset(listProps);