基础 API 介绍（C#）

用户关联

用户关联是为了对用户进行唯一标识，提高用户行为分析的准确性。目前神策提供了简易用户关联和全域用户关联分为用于支撑不同的业务场景。

• 简易用户关联（IDM2.0）
• 全域用户关联（IDM3.0）

用户属性

• 关于事件属性和用户属性的区别，请参考数据模型
• 用户属性的命名约束，请参考数据格式

针对简易用户关联和全域用户关联两种场景，用户属性的设置对应不同的接口，具体根据业务需求参照以下链接。

• 简易用户关联 API 文档（IDM2.0）
• 全域用户关联 API 文档（IDM3.0）

埋点事件采集

在 SDK 初始化完成之后，您可以通过以下接口进行数据埋点。

追踪事件

针对简易用户关联和全域用户关联两种场景，追踪事件对应不同的接口，具体根据业务需求参照以下链接。

• 简易用户关联 API 文档（IDM2.0）
• 全域用户关联 API 文档（IDM3.0）

物品元数据上报

在神策推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。神策分析 SDK 提供了设置与删除物品元数据的方法。

item_id（物品 ID ）与 item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个参数，来完成对物品的操作。

设置物品

直接设置一个物品，如果已存在则覆盖。除物品 ID 与 物品所属类型外，其他物品属性需在 $properties 中定义。

物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。

//1.接口介绍
/// 

/// 设置物品
/// 
/// 物品所属类型
/// 物品 ID
/// 相关属性
public void ItemSet(String itemType, String itemId, Dictionary properties)

//2.使用示例
Dictionary properties = new Dictionary();
properties.put("name", "C++ Primer");
properties.put("price", 31.54);
sensorsAnalytics.ItemSet("book", "0321714113", properties);

删除一个物品

如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。

除物品 ID 与 物品所属类型外，不解析其他物品属性。

//1.接口介绍
/// 

/// 删除物品
/// 
/// 物品所属类型
/// 物品 ID
public void ItemDelete(String itemType, String itemId);

//2.使用示例
sensorsAnalytics.itemDelete("book", "0321714113");

事件属性

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

• 事件属性是一个 Dictionary 对象
• Dictionary 中每个元素描述一个属性，Key 为属性名称，必需是 String 类型
• Dictionary 中，每个元素的 Value 是属性的值，支持 String、Number、List 和 Date

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

系统预置属性

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

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

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

事件公共属性

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

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

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

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

在设置事件公共属性后，实际发送的事件中会被加入 ServerVersion 和 Location 属性，等价于

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

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

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