# C# SDK 使用指南
本指南将会为您介绍如何使用 C# SDK 接入您的项目,您可以在访问GitHub (opens new window)获取 C# SDK 的源代码。
最新版本为:1.3.1
更新时间为:2021-04-22
C# SDK 下载地址 (opens new window)
# 一、集成并初始化 SDK
# 1.1 集成 SDK
C# SDK 运用于服务端 .NET Framework
的应用,下载SDK 文件 (opens new window),解压后将 dll 文件引用即可。
在头部加入以下代码引入 SDK:
using ThinkingData.Analytics
# 1.2 初始化 SDK
您可以通过三种方法获得 SDK 实例:
(1)LoggerConsumer: 批量实时写本地文件,默认以天为分隔,需要与 LogBus 搭配使用进行数据上传,建议使用
//默认按天切分文件
ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new LoggerConsumer(logDirectory));
//如果您想按小时切分文件,可如下初始化
// ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new LoggerConsumer(logDirectory,LoggerConsumer.RotateMode.HOURLY));//按小时切分,无大小切分
// 调用SDK...
// 上报数据
ta.Track(accountId, distinctId, "Payment", properties);
// 调用SDK...
// 在关闭服务器前需要调用关闭接口
ta.Close();
传入的参数为写入本地的文件夹地址,您只需将 LogBus 的监听文件夹地址设置为此处的地址,即可使用 LogBus 进行数据的监听上传。
(2)BatchConsumer: 批量实时向服务器传输数据,不需要搭配传输工具,有数据丢失的风险,请谨慎使用
ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new BatchConsumer(serverURL, appid));
//如果您想内网传输,您可以如下初始化,false代表不压缩文件,默认gzip压缩
//ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new BatchConsumer(serverURL, appid,false));
//如果你想批量上报,您可以如下初始化,现在默认是20条上报一次
//ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new BatchConsumer(serverURL, appid, 100));
serverURL
为传输数据的 URL,appid
为您的项目的 APP ID
如果您使用的是云服务,请输入以下 URL:
http://receiver.ta.thinkingdata.cn
如果您使用的是私有化部署的版本,请输入以下 URL:
http://数据采集地址
注:1.2.0 版本之前输入以下 URL:
http://receiver.ta.thinkingdata.cn/logagent
http://数据采集地址/logagent
(3)DebugConsumer : 逐条实时地向 TA 服务器传输数据,不需要搭配传输工具,如果数据出现错误,整条数据都将不会入库,并且返回详细的错误说明,不建议在生产环境中使用
ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new DebugConsumer(serverUrl,appId));
//如果您不想上传到TA库中,可如下初始化:
//ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new DebugConsumer(serverUrl,appId,true));
serverURL
为传输数据的 URL,appid
为您的项目的 APP ID
如果您使用的是云服务,请输入以下 URL:
http://receiver.ta.thinkingdata.cn
如果您使用的是私有化部署的版本,请输入以下 URL:
http://数据采集地址
# 二、上报数据
在 SDK 初始化完成之后,您就可以调用track
来上传事件,一般情况下,您可能需要上传十几到上百个不同的事件,如果您是第一次使用 TA 后台,我们推荐您先上传几个关键事件。
如果您对需要发送什么样的事件有疑惑,可以查看快速使用指南了解更多信息。
# 2.1 发送事件
您可以调用track
来上传事件,建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件,此处以用户付费作为范例:
//设置未登录状态下的访客ID
string distinctId= "distinctId";
//设置登录后的账号ID
string accountId = "accountId";
Dictionary<string, object> properties= new Dictionary<string, object>();
// 设置用户的ip地址,TA系统会根据IP地址解析用户的地理位置信息,如果不设置的话,默认不上报
properties.Add("#ip", "123.123.123.123");
// 设置事件发生的时间,如果不设置的话,则默认使用为当前时间
properties.Add("#time", DateTime.Now);
//设置事件属性
properties.Add("Product_Name", "商品A");
properties.Add("Price", 30);
properties.Add("OrderId", "订单号abc_123");
List<string> list1 = new List<string>();
list1.Add("str1");
list1.Add("str2");
list1.Add("str3");
properties.Add("array",list1);
// 上传事件,包含账号ID与访客ID
ta.Track(accountId, distinctId, "Payment", properties);
// 您也可以只上传访客ID
// ta.Track(null, distinctId, "Payment", properties);
// 或者只上传账号ID
// ta.Track(accountId, null, "Payment", properties);
注: 为了保证访客 ID 与账号 ID 能够顺利进行绑定,如果您的游戏中会用到访客 ID 与账号 ID,我们极力建议您同时上传这两个 ID,否则将会出现账号无法匹配的情况,导致用户重复计算,具体的 ID 绑定规则可参考用户识别规则一章。
- 事件的名称只能以字母开头,可包含数字,字母和下划线“_”,长度最大为 50 个字符,对字母大小写不敏感。
- 事件属性是
Dictionary<string, object>
类型,其中每个元素代表一个属性; - 事件属性
Key
为属性名称,为string
类型,规定只能以字母开头,包含数字,字母和下划线“_”,长度最大为 50 个字符,对字母大小写不敏感; - 属性值支持五种类型:字符串、数值类、
bool
、DateTime
、List
。
# 2.2 设置公共事件属性
对于一些需要出现在所有事件中的属性属性,您可以调用SetPublicProperties
来设置公共事件属性,我们推荐您在发送事件前,先设置公共事件属性。
// 设置公共事件属性
Dictionary<string, object> superProperties= new Dictionary<string, object>();
superProperties.Add("server_version", "1.2.3A");
superProperties.Add("server_name", "A1001");
ta.SetPublicProperties(superProperties);
// 设置事件属性
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("Product_Name", "商品A");
properties.Add("Price", 30);
properties.Add("OrderId", "订单号abc_123");
// 上传事件,事件中将会带有公共事件属性以及该事件本身的属性
ta.Track(accountId, distinctId, "Payment", properties);
/*
相当于进行下列操作
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("server_version", "1.2.3A");
properties.Add("server_name", "A1001");
properties.Add("Product_Name", "商品A");
properties.Add("Price", 30);
properties.Add("OrderId", "订单号abc_123");
ta.track(distinct_id,account_id,"Payment",properties)
*/
- 公共事件属性是
Dictionary<string, object>
类型,其中每个元素代表一个属性; - 公共事件属性
Key
为属性名称,为string
类型,规定只能以字母开头,包含数字,字母和下划线“_”,长度最大为 50 个字符,对字母大小写不敏感; - 公共事件属性值支持五种类型:字符串、数值类、
bool
、DateTime
、list
。
如果调用SetPublicPropperties
设置先前已设置过的公共事件属性,则会覆盖之前的属性值。如果公共事件属性和track
上传事件中的某个属性的 Key 重复,则该事件的属性会覆盖公共事件属性:
// 设置公共事件属性
Dictionary<string, object> superProperties= new Dictionary<string, object>();
superProperties.Add("server_version", "1.2.3A");
superProperties.Add("server_name", "A1001");
ta.SetPublicProperties(superProperties);
// 再次设置公共事件属性,此时"server_name"的值变为"B9999"
superProperties.clear();
superProperties.Add("server_name","B9999");
ta.SetPublicProperties(superProperties);
// 设置事件属性
Dictionary<string, Object> properties= new Dictionary<string, object>();
properties.Add("server_version", "1.3.4");
properties.Add("Product_Name", "商品A");
properties.Add("Price", 30);
properties.Add("OrderId", "订单号abc_123");
// 上传事件,此时"server_version"的值为"1.3.4","server_name"的值为"B9999"
ta.Track(accountId, distinctId, "Payment", properties);
如果您想要清空所有公共事件属性,可以调用ClearPublicProperties
。
# 三、用户属性
TA 平台目前支持的用户属性设置接口为UserSet
、UserSetOnce
、UserAdd
、UserDelete
。
# 3.1 UserSet
对于一般的用户属性,您可以调用UserSet
来进行设置,使用该接口上传的属性将会覆盖原有的属性值,如果之前不存在该用户属性,则会新建该用户属性,类型与传入属性的类型一致:
// 上传用户属性,"user_name"的值为"ABC"
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("user_name","ABC");
ta.UserSet(accountId,distinctId, properties);
properties.clear();
//再次上传用户属性,该用户的"user_name"被覆盖为"XYZ"
properties.Add("user_name","XYZ");
ta.UserSet(accountId,distinctId, properties);
UserSet
设置的用户属性是一个Dictionary<string, object>
类型,其中每个元素代表一个属性;- 用户属性
Key
为属性名称,为string
类型,规定只能以字母开头,包含数字,字母和下划线“_”,长度最大为 50 个字符,对字母大小写不敏感; - 属性值支持五种类型:字符串、数值类、
bool
、DateTime
、list
。
# 3.2 UserSetOnce
如果您要上传的用户属性只要设置一次,则可以调用UserSetOnce
来进行设置,当该属性之前已经有值的时候,将会忽略这条信息:
// 上传用户属性,"user_name"的值为"ABC"
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("user_name","ABC");
ta.UserSetOnce(accountId,distinctId, properties);
properties.clear();
//上传用户属性,该用户的"user_name"已设置因此忽略该属性设置
//该用户的"user_age"没有被设置,因此设置值为18
properties.Add("user_name","XYZ");
properties.Add("user_age",18);
ta.UserSetOnce(accountId,distinctId, properties);
UserSetOnce
设置的用户属性类型及限制条件与UserSet
一致。
# 3.3 UserAdd
当您要上传数值型的属性时,您可以调用UserAdd
来对该属性进行累加操作,如果该属性还未被设置,则会赋值 0 后再进行计算,可传入负值,等同于相减操作。
//上传用户属性,给该用户的"TotalRevenue"属性与"VipLevel"属性分别加上30和1
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("TotalRevenue",30);
properties.Add("VipLevel",1);
ta.UserAdd(accountId,distinctId, properties);
UserAdd
设置的用户属性类型及限制条件与UserSet
一致,但只对数值型的用户属性有效。
# 3.4 UserDelete
如果您要删除某个用户,可以调用UserDelete
将这名用户删除,您将无法再查询该名用户的用户属性,但该用户产生的事件仍然可以被查询到
ta.UserDelete(accountId, distinctId);
# 3.5 UserUnSet
当您需要清空某个用户的用户属性的值时,可以调用 UserUnset
进行清空:
//删除这个用户的某个属性 必须是string类型的集合,例如:
List<string> list = new List<string>();
list.Add("nickname");
list.Add("age");
ta.UserUnSet(accountId, distinctId, list);
# 3.6 UserAppend
当您要为 list 类型追加用户属性值时,您可以调用UserAppend
来对指定属性进行追加操作,如果该属性还未在集群中被创建,则UserAppend
创建该属性
//user_append,追加集合属性
Dictionary<string, object> dictionary = new Dictionary<string, object>();
List<string> list = new List<string>(); //list里面的数据最后都会tostring
list.Add("true");
list.Add("test");
dictionary.Add("arrkey4",list);
ta.UserAppend(accountId,distinctId,dictionary);
# 四、其他操作
# 4.1 立即提交数据
ta.Flush();
立即提交数据到相应的接收器
# 4.2 关闭 sdk
ta.Close();
关闭并退出 sdk,请在关闭服务器前调用本接口,以避免缓存内的数据丢失
# 五、相关预置属性
# 5.1 所有事件带有的预置属性
以下预置属性,是 C# SDK 中所有事件(包括自动采集事件)都会带有的预置属性
属性名 | 中文名 | 说明 |
---|---|---|
#ip | IP 地址 | 用户的 IP 地址,需要进行手动设置,TA 将以此获取用户的地理位置信息 |
#country | 国家 | 用户所在国家,根据 IP 地址生成 |
#country_code | 国家代码 | 用户所在国家的国家代码(ISO 3166-1 alpha-2,即两位大写英文字母),根据 IP 地址生成 |
#province | 省份 | 用户所在省份,根据 IP 地址生成 |
#city | 城市 | 用户所在城市,根据 IP 地址生成 |
#lib | SDK 类型 | 您接入 SDK 的类型,如 tga_csharp_sdk 等 |
#lib_version | SDK 版本 | 您接入 C# SDK 的版本 |
# ChangeLog
# 1.3.1 2021-04-22
- 修复 LoggerConsumer 写文件时文件锁创建失败的问题
# 1.3.0 2020-12-29
- 新增 track_update 接口,支持可更新事件
- 新增 track_overwrite 接口,支持可重写事件
- 新增 #first_check_id 属性,支持首次发生事件
- 优化 LoggerConsumer,增加指定生成文件前缀
- 优化 LoggerConsumer,增加自动创建未存在目录
# v1.2.1 2020-03-16
- 修复数据未及时 flush 问题
# v1.2.0 2020-02-13
- 数据类型支持 list 类型
- 新增 user_append 接口,支持用户的数组类型的属性追加
- 新增 user_unset 接口,支持删除用户属性
- BatchConsumer 性能优化:支持配置压缩模式;移除 Base64 编码
- DebugConsumer 优化: 在服务端对数据进行更完备准确地校验
# v1.1.0 2019-09-24
- 新增 DebugConsumer, 便于调试接口
- 优化 LoggerConsumer, 支持按小时切分日志文件
- 去掉 LoggerConsumer 单个文件默认大小为 1G 的切分
- 优化代码,修复属性为 null 时报错的 bug,提升稳定性
# v1.0.0 2019-07-09
- 上线 LoggerConsumer,BatchConsumer 的基本功能