1.
C# SDK 使用说明
在使用前,请先阅读
数据模型
的介绍。
C# SDK 适用于服务端 .NET 框架之上的应用和 C# 语言开发的客户端,目前支持 .Net Core 2.0+ 和 .Net Framework 4.6.1+;同时支持通过 NuGet 方式集成我们的 SDK。
2.
集成神策分析 SDK
在服务端 .NET 应用中集成
神策分析 SDK
,使用神策分析采集并分析用户行为。
SDK 的工程源代码可以从
GitHub
下载,并选用下面的一种方法进行集成:
-
(推荐)通过 NuGet 方式直接引入我们的 SDK:
https://www.nuget.org/packages/SensorsData.Analytics/
-
对 SDK 源代码编译后从 Release 目录下取得
dll
文件用于集成;
-
将 SDK 项目其作为
模块
添加进需要集成的项目中使用。
2.1.
初始化神策分析 SDK
2.1.1.
获取配置信息
如下图所示获取数据接收地址:
2.1.2.
在程序中初始化 SDK
在程序启动时,调用构造函数
new SensorsAnalytics(consumer)
初始化 SDK 实例。
// 使用 LoggingConsumer 初始化 SensorsAnalytics
IConsumer consumer = new LoggingConsumer("D:/test/");
SensorsAnalytics sa = new SensorsAnalytics(consumer);
// 用户的 Distinct Id
String distinctId = "ABCDEF123456789";
// 记录用户登录事件
sa.Track(distinctId, "UserLogin");
// 使用神策分析记录用户行为数据
// ...
// 强制上报数据或者落盘
sa.Flush();
// 程序生命周期结束前,停止神策分析 SDK 所有服务、释放资源
sa.Shutdown();
程序结束前需要使用
shutdown()
接口显式结束,该接口可能需要等待若干秒,直到本地缓存的数据都已发送到神策分析。至此,我们已经可以正常使用神策分析 SDK 采集用户数据了。在开发多线程程序时,开发者可以在线程间复用神策分析实例用于记录数据。
3.
设置神策分析 SDK
C# SDK 主要由以下两个组件构成:
-
SensorsAnalytics:用于发送数据的接口对象,构造函数需要传入一个 Consumer 实例
-
Consumer:Consumer 会进行实际的数据发送
为了让开发者更灵活的接入数据,建议使用 SDK 实现的如下 Consumer:
-
LoggingConsumer
-
NewClientConsumer
3.1.
LoggingConsumer(推荐)
用于将数据输出到指定目录并按天切割文件,支持通过参数指定是否按小时切割,一般用来处理实时数据,生成日志文件并使用
LogAgent
等工具导入。
接口说明:
///日志文件存放的目录,确保目录存在
LoggingConsumer(string logPath)
例子说明:
// 使用 LoggingConsumer 初始化 SensorsAnalytics
// "/Users/sa/logDir" 是存放日志的目录,需要提前创建;之后会自动在此目录下生成格式为 "yyyyMMdd.txt" 的日志文件
IConsumer consumer = new LoggingConsumer("/Users/sa/logDir");
//isLoginId bool 表示是否登录 ID
//建议将 sa 对象做单例使用
SensorsAnalytics sa = new SensorsAnalytics(consumer, isLoginId);
// 使用神策分析 记录用户行为数据
// ...
// 强制上报数据或者落盘
sa.Flush();
// 程序生命周期结束前,停止神策分析 SDK 所有服务、释放资源
sa.Shutdown();
3.2.
NewClientConsumer
适合使用 C# 语言开发的客户端,它会先将数据缓存在内存中,当数目达到配置的阈值时会自动上报数据,同时还支持定时上报功能。如果调用 ShutDown() 会将缓存中数据保存在文件中,下次初始化 SDK 时会加载到缓存中。
接口说明:
public NewClientConsumer(String serverUrl, String fileAbsolutePath, ICallback callback = null)
public NewClientConsumer(String serverUrl, String fileAbsolutePath, int bulkSize, ICallback callback = null)
public NewClientConsumer(String serverUrl, String fileAbsolutePath, ICallback callback = null, ScheduledStyle scheduledStyle = ScheduledStyle.DISABLED, int flushMillisecond = 1000)
public NewClientConsumer(String serverUrl, String fileAbsolutePath, int bulkSize, ICallback callback = null, ScheduledStyle scheduledStyle = ScheduledStyle.DISABLED, int flushMillisecond = 1000)
/// <summary>
/// NewClientConsumer Constructor
/// </summary>
/// <param name="serverUrl">数据接收地址</param>
/// <param name="fileAbsolutePath">日志文件的绝对路径,需确保该文件存在</param>
/// <param name="bulkSize">缓存事件数目,当缓存大于等于此数,将触发数据上报功能</param>
/// <param name="requestTimeoutMillisecond">数据上报的网络请求超时时间,单位是 ms</param>
/// <param name="callback">当处理数据发生异常时,会返回处理异常的数据</param>
/// <param name="scheduledStyle">定时上报任务。默认 <see cref="ScheduledStyle.DISABLED"/> 表示不开启定时刷新。<see cref="ScheduledStyle.ALWAYS_FLUSH"/>:开启定时任务,当触发定时任务时总是执行 Flush 操作。 <see cref="ScheduledStyle.BULKSIZE_FLUSH"/>:开启定时任务,当触发定时任务时缓存中事件数目超过 bulkSize 才会执行 Flush 操作。
/// 注意开启定时任务后,当调用 <see cref="SensorsAnalytics.Track(string, string)"/>方法触发事件时并且缓存中事件超过 bulkSize 也不会立即出发 <see cref="Flush"/>,而是在定时任务执行时再上报事件。
/// </param>
/// <param name="flushMillisecond">消费者线程定时执行频率,默认 1000 毫秒,最低不能小于 1000ms</param>
public NewClientConsumer(String serverUrl, String fileAbsolutePath, int bulkSize, int requestTimeoutMillisecond, ICallback callback = null, ScheduledStyle scheduledStyle = ScheduledStyle.DISABLED, int flushMillisecond = 1000)
例子说明:
//"/Users/sa/logDir/log.txt"是指定的缓存文件路径,需要提前创建。
//20 是设定的阈值,当缓存数据大于等于此值时将缓存中数据发送至服务端
//10*1000 为网络超时时间
//MyCallback 是请求失败之后异常数据回调(v2.0.5 及以上版本支持)
class MyCallback : ICallback
public void OnFailed(FailedData failedData)
//发送失败的数据处理
//下面是不支持定时上报任务的写法
//注意其中的 /Users/sa/logDir/log.txt 必须在本地存在
IConsumer consumer = new NewClientConsumer("http://newsdktest.datasink.sensorsda2ta.cn/sa?project=zhangwei&token=5a394d2405c147ca", "/Users/sa/logDir/log.txt", 10, 10 * 1000, new MyCallback())
//下面是支持定时上报任务的写法
IConsumer consumer = new NewClientConsumer("http://newsdktest.datasink.sensorsda2ta.cn/sa?project=zhangwei&token=5a394d2405c147ca", "/Users/sa/logDir/log.txt", 10, 10 * 1000, new MyCallback(), ScheduledStyle.ALWAYS_FLUSH);
//isLoginId bool 表示是否登录 ID
//建议将 sa 对象做单例使用
SensorsAnalytics sa = new SensorsAnalytics(consumer, isLoginId);
// 使用神策分析 记录用户行为数据
// ...
// 强制上报数据或者落盘
sa.Flush();
// 程序生命周期结束前,停止神策分析 SDK 所有服务、释放资源
sa.Shutdown();