C# SDK

搜索文档…
C# SDK
C# SDK 主要用于服务端或客户端 C# 应用。
SDK Releases包下载：
Github地址(推荐)：https://github.com/analysys/ans-DotNet-sdk/releases
Gitee地址：https://gitee.com/Analysys/ans-DotNet-sdk/releases
Releases中含有更新说明请您阅读，接口使用请参考本文档。
1. 集成 SDK
以 Visual Studio 为例：将需要的动态链接库Analysys.dll拷贝到本地工程目录下；在 vs 中右键工程引用->添加引用->程序集->浏览，选择Analysys.dll点击 添加，即添加引用成功。
说明：该版本动态链接库基于 .netframework4.0 进行编译的，无需其他的第三方库，如果需要其他framework的版本，请联系我们。
2. SDK 初始化
2.1 获取配置信息
需获取的配置信息为：
数据接收地址：http://host:port
2.2 初始化接口
在程序启动时（如 static void Main(string[] args) 方法中），调用构造函数 new AnalysysDotNetSdk(Collecter) 初始化 DotNet SDK 实例。如下：
1
private const string APP_KEY = "APPKEY";
2
private const string ANALYSYS_SERVICE_URL = @"http://host:port";
3
AnalysysDotNetSdk analysys = new AnalysysDotNetSdk(new SyncCollecter(ANALYSYS_SERVICE_URL), APP_KEY);;;
Copied!
APPKEY：网站获取的 Key
SyncCollecter：为实时事件收集器
事件收集器还提供批量收集器和本地落文件收集器，用户可以按照自己需求指定。
2.2.1 实时收集器
用户每触发一次上传，该收集器则立即上传数据至接收服务器：
1
public SyncCollecter(String serverUrl);
Copied!
serverUrl：数据接收地址
2.2.2 批量收集器
用户触发上传，该收集器将先缓存数据，直到数量达到用户设置的阈值或者用户设置的等待时间，才会触发真正的上传：
1
public BatchCollecter(String serverUrl);
2
public BatchCollecter(String serverUrl, int batchNum);
3
public BatchCollecter(String serverUrl, int batchNum, long batchSec);
Copied!
serverUrl：数据接收地址
batchNum：批量发送数量，默认值：20条
batchSec：批量发送等待时间(秒)，默认值：10秒
2.2.3 落地文件收集器
该收集器可以把用户触发的事件经过封装处理成标准的JSON写入本地文件中。支持多线程/多进程同时写入同一文件，默认为同步一条条写入文件，可以指定是否异步批量写入以及批量写入的条数和时间间隔。
1
public LogCollecter(String logFolder);
2
​
3
public LogCollecter(String logFolder, boolean async);
4
​
5
public LogCollecter(String logFolder, GeneralRule rule);
6
​
7
public LogCollecter(String logFolder, GeneralRule rule, boolean async);
8
​
9
public LogCollecter(String logFolder, GeneralRule rule, boolean async, int batchNum, long batchSec);
10
​
Copied!
logFolder：数据保存的目录
async： 是否异步批量保存(默认为false，如果设置为true则默认20条或者10秒进行落地操作)
rule: 文件存储规则。当传值为"GeneralRule.DAY"时，文件按日写入数据（即每日生成一个文件），当传值为"GeneralRule.HOUR"时，文件按小时写入数据（即每小时生成一个文件）。默认规则为按小时
batchNum： 批量保存数量，默认值：20条
batchSec： 批量保存等待时间(秒)，默认值：10秒
至此 SDK初始化完成，调用 SDK 提供的接口已可正常采集用户数据了
1.程序结束前建议调用Flush();接口，确保不会丢失内存缓存的数据。
2.在多线程环境中时，推荐使用单例模式初始化 AnalysysDotNetSdk，开发者可以在不同的线程间重复使用 AnalysysDotNetSdk 实例用于记录数据。
3. 基础接口介绍
3.1 Debug 模式
Debug 主要用于开发者测试，接口如下：
1
public void setDebugMode(DEBUG debug);
Copied!
debug：debug 模式,枚举类型,默认关闭状态。有以下三种枚举值：
DEBUG.CLOSE：表示关闭 Debug 模式
DEBUG.OPENNOSAVE：表示打开 Debug 模式，但该模式下发送的数据仅用于调试，不计入平台数据统计
DEBUG.OPENANDSAVE：表示打开 Debug 模式，该模式下发送的数据可计入平台数据统计
注意：发布版本时debug模式设置为`DEBUG.CLOSE`。
3.2 统计事件
事件跟踪，设置事件名称和事件详细信息。接口如下：
1
public void Track(string distinctId, bool isLogin, string eventName, Dictionary<string, object> properties, string platform);
2
public void Track(string distinctId, bool isLogin, string eventName, Dictionary<string, object> properties, string platform, string xwhen);
Copied!
distinctId：自定义设备身份标识,长度大于 0 且小于 255字符
isLogin：用户 ID 是否是登录 ID
eventName：自定义事件ID标识，以字母开头的字符串，必须由字母、数字、下划线组成，$ 开头为预置事件/属性，不支持乱码、中文、空格等，长度范围1-99字符。
properties: 自定义事件属性，最多包含 100条，且key是以字母开头的字符串，必须由字母、数字、下划线组成，字母不区分大小写，不支持乱码、中文、空格等，长度范围1-99字符；value 类型约束(String/Number/boolean/list/数组)，若为字符串,最大长度255字符
platform：平台类型,内容范围：JS、WeChat、Android、iOS
xwhen: 用户自定义时间戳(带毫秒的13位时间戳)
示例：用户浏览商品
1
//浏览商品
2
string distinctId = "1234567890987654321";
3
string platForm = "DotNet"; //DotNet平台
4
analysys.SetDebugMode(DEBUG.CLOSE); //设置debug模式
5
//浏览商品
6
Dictionary<string, object> trackPropertie = new Dictionary<string, object>();
7
trackPropertie["$ip"] = "122.122.122.122"; //IP地址
8
List<string> bookList = new List<string>();
9
bookList.Add("Thinking in Java");
10
trackPropertie["productName"] = bookList; //商品列表
11
trackPropertie["productType"] = "Java书籍"; //商品类别
12
trackPropertie["producePrice"] = 80; //商品价格
13
trackPropertie["shop"] = "xx网上书城"; //店铺名称
14
analysys.Track(distinctId, false, "ViewProduct", trackPropertie, platForm);
Copied!
3.3 用户关联
用户 ID 关联接口。将 aliasId 和 distinctId 关联，计算时会认为是一个用户的行为。该接口是在 distinctId 发生变化的时候调用，来告诉 SDK distinctId 变化前后的 ID 对应关系。该场景一般应用在用户注册/登录的过程中。比如：一个匿名用户浏览商品，系统为其分配的distinctId = "1234567890987654321"，随后该匿名用户进行注册，系统为其分配了新的注册 ID，aliasId = "ABCDEF123456789"，此时就需要调用 alias 接口对两个 ID 进行关联。接口如下：
1
public void Alias(string AliasId, string distinctId, string platform);
2
public void Alias(string AliasId, string distinctId, string platform, string xwhen);
Copied!
aliasId：用户注册 ID，长度大于 0，且小于 255字符
distinctId：自定义设备身份标识，长度大于 0，且小于 255字符
platform：平台类型,内容范围：JS、WeChat、Android、iOS
xwhen: 用户自定义时间戳(带毫秒的13位时间戳)
示例：匿名用户浏览商品到注册会员
1
// 匿名ID
2
String distinctId = "1234567890987654321";
3
String platform = "DotNet";
4
...
5
...
6
...
7
//用户注册登录
8
String registerId = "ABCDEF123456789";
9
analysys.alias(registerId, distinctId, platform);
10
​
11
// 或者也可以使用自定义的时间戳
12
String myxWhen = "1569859200000";
13
analysys.alias(registerId, distinctId, platform, myxWhen);
Copied!
3.4 用户属性设置
SDK提供以下接口供用户设置用户的属性，比如用户的年龄/性别等信息。
用户属性是一个标准的K-V结构，K和V均有相应的约束条件，如不符合则丢弃该次操作。 参数约束:
属性名称
以字母开头的字符串，必须由字母、数字、下划线组成，字母不区分大小写，$ 开头为预置事件/属性，不支持乱码、中文、空格等，长度范围1-99字符
属性值
支持部分类型：string/number/boolean/集合/数组； 若为字符串，则最大长度255字符；若为数组或集合,则最多包含100条，且key约束条件与属性名称一致,value最大长度255字符
设置单个或多个属性，如用户所在城市，用户昵称，用户头像信息等。如果之前存在，则覆盖，否则，新创建。接口如下：
1
public void ProfileSet(string distinctId, bool isLogin, Dictionary<string, object> properties, string platform);
2
public void ProfileSet(string distinctId, bool isLogin, Dictionary<string, object> properties, string platform, string xwhen);
Copied!
distinctId: 自定义设备身份标识,长度大于0且小于255字符
isLogin: 用户ID是否是登录 ID
properties: 事件属性
platform: 平台类型,内容范围：JS、WeChat、Android、iOS
xwhen: 用户自定义时间戳(带毫秒的13位时间戳)
示例：用户注册后设置用户的注册信息属性
1
Dictionary<string, object> profiles = new Dictionary<string, object>();
2
profiles["$city"] = "北京"; //城市
3
profiles["$province"] = "北京"; //省份
4
profiles["nickName"] = "昵称123"; //昵称
5
profiles["userLevel"] = 0; //用户级别
6
profiles["userPoint"] = 0; //用户积分
7
List<string> interestList = new List<string>();
8
interestList.Add("户外活动");
9
interestList.Add("足球赛事");
10
interestList.Add("游戏");
11
profiles["interest"] = interestList; //用户兴趣爱好
12
analysys.ProfileSet(registerId, true, profiles, platForm);
13
​
Copied!
4. 更多接口
4.1 用户属性
4.1.1 设置用户固有属性
只在首次设置时有效的属性。如：用户的注册时间。如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。接口如下：
1
public void ProfileSetOnce(string distinctId, bool isLogin, Dictionary<string, object> properties, string platform);
2
public void ProfileSetOnce(string distinctId, bool isLogin, Dictionary<string, object> properties, string platform, string xwhen);
Copied!
distinctId: 自定义设备身份标识,长度大于0且小于255字符
isLogin: 用户ID是否是登录 ID
properties: 事件属性
platform: 平台类型,内容范围：JS、WeChat、Android、iOS
xwhen: 用户自定义时间戳(带毫秒的13位时间戳)
示例：要统计用户注册时间
1
string registerId = "ABCDEF123456789";
2
bool isLogin = true;
3
string platform = "DotNet";
4
//用户注册时间
5
Dictionary<string, object> profile_age = new Dictionary<string, object>();
6
profile_age["registerTime"] = "20180101101010";
7
analysys.ProfileSetOnce(registerId, true, profile_age, platForm);
8
​
9
// 或者也可以使用自定义的时间戳
10
String myxWhen = "1569859200000";
11
analysys.profileSetOnce(registerId, isLogin, profile_age, platform, myxWhen);
Copied!
4.1.2 设置用户属性相对变化值
设置用户属性的单个相对变化值(相对增加,减少)，只能对数值型属性进行操作，如果这个Profile之前不存在,则初始值为0。接口如下：
1
public void profileIncrement(string distinctId, bool isLogin, Dictionary<string, object> properties, string platform);
2
public void profileIncrement(string distinctId, bool isLogin, Dictionary<string, object> properties, string platform, string xwhen);
Copied!
distinctId: 自定义设备身份标识,长度大于0且小于255字符
isLogin: 用户ID是否是登录 ID
properties: 事件属性
platform: 平台类型,内容范围：JS、WeChat、Android、iOS
xwhen: 用户自定义时间戳(带毫秒的13位时间戳)
示例：用户注册初始积分为0，在用户购买商品后，用户的积分增加20，则调用该接口，用户的积分变为0+20=20了：
1
String registerId = "ABCDEF123456789";
2
boolean isLogin = true;
3
String platform = "DotNet";
4
Map<String,Object> profile = new HashMap<>();
5
profile.put("userPoint",20);
6
analysys.profileIncrement(registerId, isLogin, profile, platform);
7
​
8
// 或者也可以使用自定义的时间戳
9
String myxWhen = "1569859200000";
10
analysys.profileIncrement(registerId, isLogin, profile, platform, myxWhen);
Copied!
4.1.3 增加列表类型的属性
为列表类型的属性增加一个或多个元素，如：用户新增兴趣爱好，接口如下：
1
public void profileAppend(string distinctId, bool isLogin, Dictionary<string, object> properties, string platform);
2
public void profileAppend(string distinctId, bool isLogin, Dictionary<string, object> properties, string platform, string xwhen);
Copied!
distinctId: 自定义设备身份标识,长度大于0且小于255字符
isLogin: 用户ID是否是登录 ID
properties: 事件属性
platform: 平台类型,内容范围：JS、WeChat、Android、iOS
xwhen: 用户自定义时间戳(带毫秒的13位时间戳)
示例：用户初始填写的兴趣爱好为["户外活动"，"足球赛事"，"游戏"]，调用该接口追加["学习"，"健身"]，则用户的爱好变为["户外活动"，"足球赛事"，"游戏"，"学习"，"健身"]
1
String registerId = "ABCDEF123456789";
2
boolean isLogin = true;
3
String platform = "DotNet";
4
Map<String,Object> profile = new HashMap<>();
5
List<String> interestList = new ArrayList<String>();
6
interestList.add("户外活动");
7
interestList.add("足球赛事");
8
interestList.add("游戏");
9
profile.put("interest", interestList);//用户兴趣爱好
10
analysys.profileAppend(registerId, isLogin, profile, platform);
11
​
12
// 或者也可以使用自定义的时间戳
13
String myxWhen = "1569859200000";
14
analysys.profileAppend(registerId, isLogin, profile, platform, myxWhen);
Copied!
4.1.4 删除设置的属性值
删除设置的属性值。接口如下：
1
public void ProfileUnSet(string distinctId, bool isLogin, string property, string platform);
2
public void ProfileUnSet(string distinctId, bool isLogin, string property, string platform, string xwhen);
3
public void ProfileDelete(string distinctId,bool isLogin, string platform);
4
public void ProfileDelete(string distinctId,bool isLogin, string platform, string xwhen)
Copied!
distinctId: 自定义设备身份标识,长度大于0且小于255字符
isLogin: 用户ID是否是登录 ID
propertie: 事件属性
platform: 平台类型,内容范围：JS、WeChat、Android、iOS
xwhen: 用户自定义时间戳(带毫秒的13位时间戳)
示例1： 要删除已经设置的用户昵称这一用户属性
1
String registerId = "ABCDEF123456789";
2
boolean isLogin = true;
3
String platform = "DotNet";
4
// 删除单个用户属性
5
analysys.profileUnSet(registerId, isLogin, "nickName", platform);
6
​
7
// 或者也可以使用自定义的时间戳
8
String myxWhen = "1569859200000";
9
analysys.profileUnSet(registerId, isLogin, "nickName", platform, myxWhen);
Copied!
示例2：要删除已经设置的所有用户属性
1
String registerId = "ABCDEF123456789";
2
boolean isLogin = true;
3
String platform = "DotNet";
4
// 清除所有属性
5
analysys.profileDelete(registerId, isLogin, platform);
6
​
7
// 或者也可以使用自定义的时间戳
8
String myxWhen = "1569859200000";
9
analysys.profileDelete(registerId, isLogin, platform, myxWhen);
Copied!
4.2 通用属性
如果某个事件的属性，在所有事件中都会出现，则这个属性可以做为通用属性，通过 registerSuperProperties() 将该属性设置为事件通用属性，则设置后每次发送事件的时候都会带有该属性。比如用户浏览/购买商品过程中的用户等级就可以作为通用属性。
通用属性是一个标准的 K-V 结构，K 和 V 均有相应的约束条件，如不符合则丢弃该次操作。
约束条件如下:
属性名称
以字母开头的字符串，必须由字母、数字、下划线组成，字母不区分大小写，$ 开头为预置事件/属性，不支持乱码、中文、空格等，长度范围1-99字符
属性值
支持部分类型：string/number/boolean/集合/数组;
若为字符串,则最大长度 255字符;
若为数组或集合,则最多包含 100条,且 key 约束条件与属性名称一致,value 最大长度 255字符
4.2.1 注册通用属性
以用户浏览/购买商品的过程中发生的事件为例，用户的级别/积分就可以作为通用的属性，通过把用户级别/积分注册为通用属性，就可以避免在每次收集事件属性的时候都要手工设置该属性值。接口如下：
1
public void registerSuperProperties(Map<String, Object> params);
Copied!
params：设置多个属性
示例：
1
// 设置多个通用属性
2
Dictionary<string, object> superPropertie = new Dictionary<string, object>();
3
superPropertie.put("userLevel", 0); //用户级别
4
superPropertie.put("userPoint", 0); //用户积分
5
analysys.registerSuperProperties(superPropertie);
Copied!
4.2.2 删除通用属性
如果要删除某个通用属性或者删除全部的通用属性，可以分别调用 unregisterSuperProperty 或 clearSuperProperties 接口。具体接口定义如下：
1
public void unRegisterSuperProperty(String key);
2
public void clearSuperProperties();
Copied!
key：属性名称
示例1：删除设置的用户积分属性
1
// 删除单个通用属性
2
analysys.unRegisterSuperProperty("userPoint");
3
​
4
示例2：清除所有已经设置的通用属性
5
// 清除所有通用属性
6
analysys.clearSuperProperties();
Copied!
4.2.3 获取通用属性
由属性名称查询获取单条通用属性，或者获取全部的通用属性。接口如下：
1
public Object getSuperProperty(String key);
2
public Map<String, Object> getSuperProperties();
Copied!
key：属性名称
示例1：查看已经设置的 userLevel 通用属性
1
// 获取单个通用属性
2
analysys.getSuperProperty("userLevel")
3
​
4
示例2：查看所有已经设置的通用属
5
// 获取所有通用属
6
analysys.getSuperProperties();
Copied!
4.3  刷新缓存
立即发送所有收集的信息到服务器。
1
analysys.flush();
Copied!
5. SDK 使用样例
1
//AnalysysDotNetSdk analysys = new AnalysysDotNetSdk(new SyncCollecter(ANALYSYS_SERVICE_URL), APP_KEY);
2
//批量
3
// AnalysysDotNetSdk analysys = new AnalysysDotNetSdk(new BatchCollecter(ANALYSYS_SERVICE_URL), APP_KEY);
4
//落文件
5
AnalysysDotNetSdk analysys = new AnalysysDotNetSdk(new LogCollecter(@"SAVE_DIR"), APP_KEY);
6
try {
7
    string distinctId = "1234567890987654321";
8
    string platForm = "DotNet"; //DotNet平台
9
    analysys.SetDebugMode(DEBUG.CLOSE); //设置debug模式
10
    //浏览商品
11
    Dictionary<string, object> trackPropertie = new Dictionary<string, object>();
12
    trackPropertie["$ip"] = "122.122.122.122"; //IP地址
13
    List<string> bookList = new List<string>();
14
    bookList.Add("Thinking in Java");
15
    trackPropertie["productName"] = bookList; //商品列表
16
    trackPropertie["productType"] = "Java书籍"; //商品类别
17
    trackPropertie["producePrice"] = 80; //商品价格
18
    trackPropertie["shop"] = "xx网上书城"; //店铺名称
19
    analysys.Track(distinctId, false, "ViewProduct", trackPropertie, platForm);
20
​
21
    //用户注册登录
22
    string registerId = "ABCDEF123456789";
23
    analysys.Alias(registerId, distinctId, platForm);
24
​
25
    //设置公共属性
26
    Dictionary<string, object> superPropertie = new Dictionary<string, object>();
27
    superPropertie["sex"] = "male"; //性别
28
    superPropertie["age"] = 23; //年龄
29
    analysys.RegisterSuperProperties(superPropertie);
30
    //用户信息
31
    Dictionary<string, object> profiles = new Dictionary<string, object>();
32
    profiles["$city"] = "北京"; //城市
33
    profiles["$province"] = "北京"; //省份
34
    profiles["nickName"] = "昵称123"; //昵称
35
    profiles["userLevel"] = 0; //用户级别
36
    profiles["userPoint"] = 0; //用户积分
37
    List<string> interestList = new List<string>();
38
    interestList.Add("户外活动");
39
    interestList.Add("足球赛事");
40
    interestList.Add("游戏");
41
    profiles["interest"] = interestList; //用户兴趣爱好
42
    analysys.ProfileSet(registerId, true, profiles, platForm);
43
​
44
    //用户注册时间
45
    Dictionary<string, object> profile_age = new Dictionary<string, object>();
46
    profile_age["registerTime"] = "20180101101010";
47
    analysys.ProfileSetOnce(registerId, true, profile_age, platForm);
48
​
49
    //重新设置公共属性
50
    analysys.ClearSuperProperties();
51
    superPropertie.Clear();
52
    superPropertie = new Dictionary<string, object>();
53
    superPropertie["userLevel"] = 0; //用户级别
54
    superPropertie["userPoint"] = 0; //用户积分
55
    analysys.RegisterSuperProperties(superPropertie);
56
​
57
    //再次浏览商品
58
    trackPropertie.Clear();
59
    trackPropertie["$ip"] = "122.122.122.122"; //IP地址
60
    List<string> abookList = new List<string>();
61
    abookList.Add("Thinking in Java");
62
    trackPropertie["productName"] = bookList; //商品列表
63
    trackPropertie["productType"] = "Java书籍"; //商品类别
64
    trackPropertie["producePrice"] = 80; //商品价格
65
    trackPropertie["shop"] = "xx网上书城"; //店铺名称
66
    analysys.Track(registerId, true, "ViewProduct", trackPropertie, platForm);
67
​
68
    //订单信息
69
    trackPropertie.Clear();
70
    trackPropertie["orderId"] = "ORDER_12345";
71
    trackPropertie["price"] = 80;
72
    analysys.Track(registerId, true, "Order", trackPropertie, platForm);
73
​
74
    //支付信息
75
    trackPropertie.Clear();
76
    trackPropertie["orderId"] = "ORDER_12345";
77
    trackPropertie["productName"] = "Thinking in Java";
78
    trackPropertie["productType"] = "Java书籍";
79
    trackPropertie["producePrice"] = 80;
80
    trackPropertie["shop"] = "xx网上书城";
81
    trackPropertie["productNumber"] = 1;
82
    trackPropertie["price"] = 80;
83
    trackPropertie["paymentMethod"] = "AliPay";
84
    analysys.Track(registerId, true, "Payment", trackPropertie, platForm);
85
}
86
catch (Exception e) {
87
    Console.WriteLine(e);
88
}
89
    analysys.Flush();
Copied!