目录
此内容是否有帮助?

# C# SDK 使用指南

本指南将会为您介绍如何使用 C# SDK 接入您的项目，您可以在访问GitHub (opens new window)获取 C# SDK 的源代码。

最新版本为：1.4.0

更新时间为：2022-05-06

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:

https://global-receiver-ta.thinkingdata.cn

如果您使用的是私有化部署的版本，请输入以下 URL:

http://数据采集地址

注：1.2.0 版本之前输入以下 URL:

https://global-receiver-ta.thinkingdata.cn/logagent
http://数据采集地址/logagent

(3)AsyncBatchConsumer： 批量异步实时向服务器传输数据，不需要搭配传输工具，有数据丢失的风险，请谨慎使用

使用方法参考 BatchConsumer

(4)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:

https://global-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);
//复杂属性-对象
Dictionary<string, Object> subDic1 = new Dictionary<string, object>();
subDic1.Add("subKey", "subValue");
properties.Add.Add("subDic", subDic1);
//复杂属性-对象组
List<Object> subList1 = new List<Object>();
subList1.Add(subDic1);
properties.Add.Add("subList", subList1);

// 上传事件，包含账号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、Dictionary；

Dictionary中的值可以为字符串、数值、bool、DateTime、List<string>；

List中的值可以为字符串和Dictionary

注意：

Dictionary需配合TA后台v3.5及后续版本使用

# 三、用户属性

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

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

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

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

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

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

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

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

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

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

# 3.7 UserUniqAppend

当您要为 list 类型追加用户属性值，但不希望出现重复值时，您可以调用 UserUniqAppend 来对指定属性进行追加操作，如果该属性还未在集群中被创建，则 UserUniqAppend 创建该属性

 //user_uniq_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.UserUniqAppend(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 的版本

# 六、进阶功能

从 v1.3.0 开始，SDK 支持上报两种特殊类型事件: 可更新事件、可重写事件。这两种事件需要配合 TA 系统 2.8 及之后的版本使用。由于特殊事件只在某些特定场景下适用，所以请在数数科技的客户成功和分析师的帮助下使用特殊事件上报数据。

# 6.1 可更新事件

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

//设置未登录状态下的访客ID
string distinctId= "distinctId";
//设置登录后的账号ID
string accountId = "accountId";
//可更新事件ID
string event_id = "test_event_id";
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("Price", 35);

// 上传可更新事件，包含账号ID与访客ID
ta.TrackUpdate(accountId, distinctId, "updatable_event", event_id, properties);

# 6.2 可重写事件

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

//设置未登录状态下的访客ID
string distinctId= "distinctId";
//设置登录后的账号ID
string accountId = "accountId";
//可重写事件ID
string event_id = "test_event_id";
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("Price", 35);

// 上传可更新事件，包含账号ID与访客ID
ta.TrackOverwrite(accountId, distinctId, "overwrite_event", event_id, properties);

# 6.3 首次事件

使用“首次事件校验”特性，需要指定首次事件 ID，该 ID 首条出现的数据将入库，之后出现的都无法入库。不同事件的首次事件 ID互相独立，因此每个事件的首次校验互不干扰

//设置未登录状态下的访客ID
string distinctId= "distinctId";
//设置登录后的账号ID
string accountId = "accountId";
//可重写事件ID
string first_check_id = "test_first_check_id";
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("Price", 35);

// 上传首次事件，包含账号ID与访客ID
ta.TrackFirst(accountId, distinctId, "first_event", first_check_id, dic2);

# ChangeLog

# v1.4.0 2022/05/06

  • 新增支持动态公共属性
  • 新增首次事件接口
  • 新增 UserUniqAppend 去重追加用户属性
  • 新增支持复杂事件属性
  • 新增支持批量异步上报事件

# v1.3.1 2021/04/22

  • 修复 LoggerConsumer 写文件时文件锁创建失败的问题

# v1.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 的基本功能

← Erlang SDK 使用指南 →