C# SDK 使用说明

最后更新于:2018-10-26 09:12:34

在使用前,请先阅读数据模型的介绍。

C# SDK 主要适用于服务端 .NET Framework 之上的应用。

1. 集成神策分析 SDK

在服务端 .net 应用中集成 神策分析 SDK,使用神策分析采集并分析用户行为。

SDK 的工程源代码可以从 Github 下载 https://github.com/sensorsdata/sa-sdk-dotnet,并选用下面的一种方法进行集成:

  1. (推荐)对 SDK 源代码编译后从 Release 目录下取得 dll 文件用于集成;
  2. 将 SDK 项目其作为模块添加进需要集成的项目中使用;

2. 初始化神策分析 SDK

2.1 获取配置信息

首先从神策分析的主页中,获取数据接收的 URL 和 Token(Cloud 版)。

如果使用神策分析 Cloud 服务,需获取的配置信息为:

如果用户使用单机版私有部署的神策分析,默认的配置信息为:

如果用户使用集群版私有部署的神策分析,默认的配置信息为:

其中 {$host_name} 可以是集群中任意一台机器。

如果私有部署的过程中修改了 Nginx 的默认配置,或通过 CDN 等访问神策分析,则请咨询相关人员获得配置信息。

2.2 在程序中初始化 SDK

在程序启动时(如 static void Main(string[] args) 方法中),调用构造函数 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");

    // 使用神策分析记录用户行为数据
    // ...

    // 程序结束前,停止神策分析 SDK 所有服务
    sa.Shutdown();

程序结束前需要使用 shutdown() 接口显式结束,该接口可能需要等待若干秒,直到本地缓存的数据都已发送到神策分析。

至此,我们已经可以正常使用神策分析 SDK 采集用户数据了。在开发多线程程序时,开发者可以在线程间复用神策分析实例用于记录数据。

3. 追踪事件

第一次接入神策分析时,建议先追踪 3~5 个关键的事件,只需要几行代码,便能体验神策分析的分析功能。例如:

  • 图片社交产品,可以追踪用户浏览图片和评论事件
  • 电商产品,可以追踪用户注册、浏览商品和下订单等事件

Sensors Analytics SDK 初始化成功后,可以通过 track() 记录事件,必须包含用户 ID(distinctId)和事件名(eventName)这两个参数,同时可以传入一个 Map<String, Object> 对象,为事件添加自定义事件属性,在自定义属性中需要包含 $is_login_id 属性来说明 distinct_id 是否为登录 ID。以电商产品为例,可以这样追踪一次购物行为:


    // 用户的 Distinct Id
    String distinctId = "ABCDEF123456789";

    // 用户浏览商品
    Dictionary<string, Object> properties = new Dictionary<string, object>();

      // '$time' 属性是系统预置属性,表示事件发生的时间,如果不填入该属性,则默认使用系统当前时间
      properties.Add("$time", new Date());
      // '$ip' 属性是系统预置属性,如果服务端中能获取用户 IP 地址,并填入该属性,神策分析会自动根据 IP 地址解析用户的省份、城市信息
      properties.Add("$ip", "123.123.123.123");
      // $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 true,否则为 false,默认为 false
      properties.Add("$is_login_id", true);
      // 商品 ID
      properties.Add("ProductId", "123456");
      // 商品类别
      properties.Add("ProductCatalog", "Laptop Computer");
      // 是否加入收藏夹,Boolean 类型的属性
      properties.Add("isAddedToFav", true);

      // 记录用户浏览商品事件
      sa.Track(distinctId, "ViewProduct", properties);
    }

3.1 事件属性

如前文中的样例,追踪的事件可以设置自定义的事件属性,例如浏览商品事件中,将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中,事件属性可以作为统计过滤条件使用,也可以作为维度进行多维分析。对于事件属性,神策分析有一些约束:

  • 事件属性是一个 Map<String, Object> 对象
  • Map<String, Object> 中每个元素描述一个属性,Key 为属性名称,必需是 String 类型
  • Map<String, Object> 中,每个元素的 Value 是属性的值,支持 StringNumberList<String>Date

对于神策分析中事件属性的更多约束,请参考 数据格式。在开发多线程程序时,开发者不能在线程间复用传入的属性对象。

3.1.1 系统预置属性

如前文中样例,事件属性中以 '$' 开头的属性为系统预置属性,在自定义事件属性中填入对应 '$' 开头的属性值可以覆盖这些预置属性:

  • $ip - 填入该属性,神策分析会自动根据 IP 地址解析用户的省份、城市信息,该属性值为 String 类型;
  • $time - 填入该属性,神策分析将事件时间设置为属性值的时间,该属性值必须为 Date 类型。请注意,神策分析默认会过滤忽略 365 天前或 3 天后的数据,如需修改请联系我们。

关于其他更多预置属性,请参考 数据格式 中 '预置属性' 一节。

3.1.2 事件公共属性

特别地,如果某个事件的属性,在所有事件中都会出现,可以通过 RegisterSuperPropperties() 将该属性设置为事件公共属性。例如电商产品中的用户等级,常作为事件的公共属性,设置方法如下:

    Dictionary<string, Object> properties = new Dictionary<string, object>();
    // 服务器应用版本
    properties.Add("ServerVersion", "1.2");
    // 服务器机房地址
    properties.Add("Location", "BeiJing");
    // 设置事件公共属性
    sa.RegisterSuperPropperties(properties);

成功设置事件公共属性后,再通过 track() 追踪事件时,事件公共属性会被添加进每个事件中,例如:

    Dictionary<string, Object> properties = new Dictionary<string, object>();
    // 登录客户端 IP 地址
    properties.Add("$ip", "123.123.123.123");
    // 追踪用户登录事件
    sa.Track("ABCDEF123456789", "UserLogin", properties);

在设置事件公共属性后,实际发送的事件中会被加入 ServerVersionLocation 属性,等价于

    Dictionary<string, Object> properties = new Dictionary<string, object>();
    // 事件公共属性
    properties.Add("ServerVersion", "1.2");
    properties.Add("Location", "BeiJing");
    // 登录客户端 IP 地址
    properties.Add("$ip", "123.123.123.123");
    // 追踪用户登录事件
    sa.Track("ABCDEF123456789","UserLogin", properties);

使用 ClearSuperProperties() 会删除所有已设置的事件公共属性。

当事件公共属性和事件属性的 Key 冲突时,事件属性优先级最高,它会覆盖事件公共属性。

4. 用户识别

在服务端应用中,神策分析也要求为每个事件设置用户的 Distinct Id,这有助于神策分析提供更准确的留存率等数据。

对于注册用户,推荐使用系统中的用户 ID 作为 Distinct Id,不建议使用用户名、Email、手机号码等可以被修改的信息;

对于未注册的匿名用户:

  1. 如果前端网页中使用了 JavaScript SDK,您可以在 Cookie 里面找到 key 为 sensorsdata2015jssdkcross 的 value 值然后进行 decodeURIComponent 解 码,最后通过 JSON.parse 方法得到一个对象,对象里面的 distinct_id 即为用户所需要的。
  2. 如果 APP 中嵌入了 iOS SDKAndroid SDK,您需要自己将匿名 ID 传到服务器端应用,然后获取这个匿名 ID 作为用户标识 Distinct Id。
  3. 如果您没有使用前端 SDK (JS SDK / iOS SDK / Android SDK),则服务端也要生成一个随机 ID 作为用户标识 Distinct Id。每一个随机 ID 被认为一个独立的用户。

所有的 track 和 profile 系列方法都必须同时指定用户 ID用户 ID 是否为登录 ID 这两个参数,以便明确告知神策分析用户 ID 的类型。

4.1 用户注册/登录

当同一个用户的 Distinct Id 发生变化时(一般情况为匿名用户注册行为),可以通过 trackSignUp() 将旧的 Distinct Id 和新的 Distinct Id 关联,以保证用户分析的准确性。例如:

    // 匿名 ID 由前端传过来
    String anonymousId = "9771C579-71F0-4650-8EE8-8999FA717761";

    // 注册用户的真实 ID
    String registerId = "0012345678";
    // 用户注册/登录时,将用户注册 ID 与 匿名 ID 关联
    sa.TrackSignUp(registerId, anonymousId);

注意,对同一个用户,TrackSignUp() 只可调用一次(通常在用户 注册 时调用),多次调用 TrackSignUp() 时,只有第一次关联行为是有效的。用户 登录 前后的行为的关联建议在业务端实现。更详细的说明请参考 如何准确的标识用户,并在必要时联系我们的技术支持人员。

5. 设置用户属性

为了更准确地提供针对人群的分析服务,神策分析 SDK 可以设置用户属性,如年龄、性别等。用户可以在留存分析、分布分析等功能中,使用用户属性作为过滤条件或以用户属性作为维度进行多维分析。

使用 ProfileSet() 设置用户属性:

    String distinctId = "ABCDEF123456789";

   Dictionary<string, Object> properties = new Dictionary<string, object>();
    // 设置用户等级属性(Level)为 VIP
    properties.Add("UserLv", "Elite VIP");
    // $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 true,否则为 false,默认为 false
    properties.Add("$is_login_id", true);

    sa.ProfileSet(distinctId, properties);

对于不再需要的用户属性,可以通过 ProfileUnset() 接口将属性删除。

用户属性中,属性名称与属性值的约束条件与事件属性相同,详细说明请参考 数据格式

5.1 记录初次设定的属性

对于只在首次设置时有效的属性,我们可以使用 ProfileSetOnce() 记录这些属性。与 ProfileSet() 接口不同的是,如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据>,如果属性不存在则会自动创建。因此,profileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如:


    String distinctId = "ABCDEF123456789";

    Dictionary<string, Object> properties = new Dictionary<string, object>();
     // 设置用户渠道属性(AdSource)为 "App Store"
    properties.Add("AdSource", "App Store");
    // $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 true,否则为 false,默认为 false
    properties.Add("$is_login_id", true);

    sa.ProfileSetOnce(distinctId,properties);

    // 再次设置用户渠道属性(AdSource),设定无效,属性 "AdSource" 的值仍为 "App Store"
    properties.Add("AdSource", "Search Engine");

    sa.ProfileSetOnce(distinctId, properties);

5.2 数值类型的属性

对于数值型的用户属性,可以使用 ProfileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如:

    String distinctId = "ABCDEF123456789";

    Dictionary<string, Object> properties = new Dictionary<string, object>();
    // 设置用户游戏次数属性(GamePlayed),将次数累加1次
    properties.Add("GamePlayed", 1);
    // $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 true,否则为 false,默认为 false
    properties.Add("$is_login_id", true);

    sa.ProfileIncrement(distinctId,properties );

5.3 列表类型的属性

对于用户喜爱的电影、用户点评过的餐厅等属性,可以记录列表型属性。需要注意的是,列表型属性中的元素必须为 String 类型,且元素的值会自动去重。关于列表类型限制请见 数据格式 7.3 属性长度限制

    String distinctId = "ABCDEF123456789";

    // 电影列表
    List<String> movies = new List<String>();
    movies.Add("Sicario");
    movies.Add("Love Letter");

    // 游戏列表
    List<String> games = new List<String>();
    games.Add("Call of Duty");
    games.Add("Halo");

    // 用户属性
    Dictionary<string, Object> properties = new Dictionary<string, object>();
    properties.Add("movies", movies);
    properties.Add("games", games);
    // $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 true,否则为 false,默认为 false
    properties.Add("$is_login_id", true);

    // 传入properties,设置用户喜欢的电影属性(movies)和喜欢的游戏属性(games)
    // 设置成功后,"movies" 属性值为 ["Sicario", "Love Letter"];"games" 属性值为 ["Call of Duty", "Halo"]
    sa.ProfileAppend(distinctId, properties);

    // 传入属性名称和需要插入属性的值,设置用户喜欢的电影属性(movies)
    // 设置成功后 "movies" 属性值为 ["Sicario", "Love Letter", "Dead Poets Society"]
    sa.ProfileAppend(distinctId, "movies", "Dead Poets Society");

    // 传入属性名称和需要插入属性的值,设置用户喜欢的电影属性(movies),
    // 但属性值 "Love Letter" 与已列表中已有元素重复,操作无效,
    // "movies" 属性值仍然为 ["Sicario", "Love Letter", "Dead Poets Society"]
    sa.ProfileAppend(distinctId, "movies", "Love Letter");

6. 设置神策分析 SDK

以下内容说明如何更精细地控制神策分析 SDK 的行为。

6.1. 数据采集

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

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

为了让开发者更灵活的接入数据,神策分析 SDK 实现了以下 Consumer:

  • LoggingConsumer: 用于将数据输出到指定目录,并使用 LogAgent 等工具导入,该工具能保证导入不重复、不遗漏。

    // 使用 LoggingConsumer 初始化 SensorsAnalytics
    // D:/test/ 是文件路径
    // 日志文件名 roller.DatePattern = @"yyyyMMdd'.txt'";
    IConsumer consumer = new LoggingConsumer("D:/test/");
            SensorsAnalytics sa = new SensorsAnalytics(consumer);

    // 使用神策分析 记录用户行为数据
    // ...

    // 程序结束前,停止神策分析 SDK 所有服务
    sa.Shutdown();