Unity Sdk by ThinkingDataAnalytics - 1

SDK

ThinkingData SDK for Unity 3D

Unknown VersionApache License 2.0Updated 7 days agoCreated on July 26th, 2019
Go to source

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 平台目前支持的用户属性设置接口为UserSetUserSetOnceUserAddUserDelete

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);
Show all projects by ThinkingDataAnalytics