C# SDK 使用指南

提示

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

您可以在 GitHub (opens new window) 获取C# SDK 源码。

C# SDK 支持在Mac、Windows平台运行，大小约为 29KB

最新版本为: v1.0.0

更新时间为: 2022-06-09

C# 客户端 SDK 是为 Windows Form 桌面开发提供的一款数据采集SDK。

一、初始化 SDK

1.1 集成SDK

下载在 GitHub (opens new window) 获取C# SDK 源码，将目录下的 ThinkingData.cs 文件添加至项目中。

SDK依赖Newtonsoft.Json框架用作json解析，如您是使用Visual Studio，请使用NuGet加入Newtonsoft.Json库。

1.2 初始化SDK

引入ThinkingData.Analytics，使用ThinkingdataAnalytics类初始化TA实例。

using ThinkingData.Analytics;

ThinkingdataAnalytics ta = new ThinkingdataAnalytics("35a15b58ae934f3994c1abf77910e390", "https://global-receiver-ta.thinkingdata.cn/");

二、设置用户 ID

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

2.1 设置访客 ID

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

ta.SetIdentity("identity")

2.2 设置与清除账号 ID

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

ta.login("login");

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

三、上传事件

3.1 上传事件

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

Dictionary<string, Object> dic2 = new Dictionary<string, object>();
dic2.Add("id", 618834);
dic2.Add("create_date", Convert.ToDateTime("2019-7-8 20:23:22"));
dic2.Add("group_no", "T22514");
dic2.Add("group_title", "【爆款拼装来袭】");
dic2.Add("group_purchase_id", 438);
dic2.Add("group_order_is_vip", 3);
dic2.Add("service_id", 0);
ta.Track( "testEventName2", dic2);

• 事件属性是 Dictionary 类型，其中每个元素代表一个属性；
• 事件属性 Key 为属性名称，为 string 类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感；
• 属性值支持六种类型：字符串、数值类、bool、List 类型。

四、用户属性

TA 平台目前支持的用户属性设置接口为 UserSet、UserSetOnce、UserAdd、UserUnSet、UserDelete、UserAppend.

4.1 UserSet

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

Dictionary<string, Object> dic7 = new Dictionary<string, object>();
dic7.Add("double1", (double)1);
dic7.Add("string1", "string");
dic7.Add("boolean1", true);
dic7.Add("DateTime4", DateTime.Now);
List<string> list5 = new List<string>();
list5.Add("6.66");
list5.Add("test");
dic7.Add("arrkey4", list5);
ta.UserSet(dic7);

属性格式要求与事件属性保持一致。

4.2 UserSetOnce

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

Dictionary<string, Object> dic5 = new Dictionary<string, object>();
dic5.Add("login_name", "皮2");
dic5.Add("#time", new DateTime(2019, 12, 10, 15, 12, 11, 444));
dic5.Add("#ip", "192.168.1.1");
//dic5.Add("#uuid",Guid.NewGuid().ToString("D")); 上传#uuid为标准格式(8-4-4-4-12)的string,服务端比较稳定，可不上传
ta.UserSetOnce(dic5);

属性格式要求与事件属性保持一致。

4.3 UserAdd

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

Dictionary<string, Object> dic4 = new Dictionary<string, object>();
dic4.Add("TotalRevenue", 648);
ta.UserAdd( dic4);

设置的属性key为字符串，Value 只允许为数值。

4.4 UserUnSet

如果您需要重置用户的某个属性，可以调用 UserUnset 将该用户指定用户属性的值清空，此接口支持传入字符串或者列表类型的参数:

List<string> list2 = new List<string>();
list2.Add("nickname");
list2.Add("age");
ta.UserUnSet(list2);

传入值为被清空属性的 Key 值。

4.5 UserDelete

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

ta.UserDelete();

4.6 UserAppend

您可以调用 UserAppend 为 List 类型的用户属性追加元素:

Dictionary<string, object> dictionary = new Dictionary<string, object>();
List<string> list6 = new List<string>();
list6.Add("true");
list6.Add("test");
dictionary.Add("arrkey4", list6);
ta.UserAppend( dictionary);

五、进阶功能

C# SDK 支持上报三种特殊类型事件: 首次事件、可更新事件、可重写事件。

5.1 首次事件

首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上第一次发生的事件，则可以用首次事件来上报数据。

Dictionary<string, Object> dic2 = new Dictionary<string, object>();
dic2.Add("id", 618834);
dic2.Add("create_date", Convert.ToDateTime("2019-7-8 20:23:22"));
dic2.Add("group_no", "T22514");
// 自定义维度
ta.TrackFirst("firstEventName", "firstEventId", dic2);
// 以设备维度
ta.TrackFirst("firstEventName", dic2);

注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 1 小时入库。

5.2 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

Dictionary<string, Object> dic2 = new Dictionary<string, object>();
dic2.Add("id", 618834);
dic2.Add("create_date", Convert.ToDateTime("2019-7-8 20:23:22"));
dic2.Add("group_no", "T22514");
ta.TrackUpdate("updateEventName", "updateEventId", dic2);

5.3 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

Dictionary<string, Object> dic2 = new Dictionary<string, object>();
dic2.Add("id", 618834);
dic2.Add("create_date", Convert.ToDateTime("2019-7-8 20:23:22"));
dic2.Add("group_no", "T22514");
ta.TrackOverwrite( "overwriteEventName", "overwriteEventId", dic2);

六、其他配置选项

6.2 打印上传数据 Log

ThinkingdataAnalytics.setLoggingType(TALogging.TALoggingLog);

七、相关预置属性

7.1 预置属性说明

各个平台采集的预制属性会有一定的差异

属性名	中文名	说明
#os	操作系统	如 MacOS, Windows等
#device_id	设备 ID	用户的设备 ID
#lib	SDK 类型	您接入 SDK 的类型，如 Android，iOS 等
#lib_version	SDK 版本	您接入 SDK 的版本

ChangeLog

v1.0.0 2022/06/09

• 支持 访客 ID 和 用户账号 的设置
• 支持事件和用户属性上报
• 支持首次、更新、重写事件的上报
• 支持Windows数据上报