1. C# SDK 使用说明

在使用前，请先阅读数据模型的介绍。
C# SDK 适用于服务端 .NET 框架之上的应用和 C# 语言开发的客户端，目前支持 .Net Core 2.0+ 和 .Net Framework 4.6.1+；同时支持通过 NuGet 方式集成我们的 SDK。

2. 集成神策分析 SDK

在服务端 .NET 应用中集成 神策分析 SDK，使用神策分析采集并分析用户行为。
SDK 的工程源代码可以从 GitHub 下载，并选用下面的一种方法进行集成：

  1. (推荐）通过 NuGet 方式直接引入我们的 SDK: https://www.nuget.org/packages/SensorsData.Analytics/
  2. 对 SDK 源代码编译后从 Release 目录下取得  dll 文件用于集成；
  3. 将 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();
C#

程序结束前需要使用 shutdown() 接口显式结束，该接口可能需要等待若干秒，直到本地缓存的数据都已发送到神策分析。至此，我们已经可以正常使用神策分析 SDK 采集用户数据了。在开发多线程程序时，开发者可以在线程间复用神策分析实例用于记录数据。

3. 设置神策分析 SDK

C# SDK 主要由以下两个组件构成:

  • SensorsAnalytics：用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例
  • Consumer：Consumer 会进行实际的数据发送

为了让开发者更灵活的接入数据，建议使用 SDK 实现的如下 Consumer：

  • LoggingConsumer
  • NewClientConsumer

3.1. LoggingConsumer（推荐）

用于将数据输出到指定目录并按天切割文件，支持通过参数指定是否按小时切割，一般用来处理实时数据，生成日志文件并使用 LogAgent 等工具导入。

接口说明：

///日志文件存放的目录，确保目录存在
LoggingConsumer(string logPath)
C#

例子说明：

// 使用 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();
C#

注意

支持多个进程写同一个目录（目录不能是 nas、nfs 类文件系统），生成的文件始终是带日期后缀的，默认每天一个。 

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


例子说明：

//"/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();
C#


注意

NewClientConsumer 默认只会在达到阈值时才会上报数据，用户可以使用 Flush() 方法主动上报数据。 

4. API 接口

针对 API 接口的使用文档，参照基础 API 使用文档介绍。