简易用户关联 API（C#）

用户关联

在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct ID，这有助于神策分析提供更准确的留存率等数据。对于注册用户，推荐使用系统中的用户 ID 作为 Distinct ID，不建议使用用户名、Email、手机号码等可以被修改的信息。

所有的 Track 和 Profile 系列方法建议明确指定 isLoginId 参数，以便明确告知神策分析用户 ID 的类型。

用户注册/登录

当同一个用户的 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() 一般情况下建议只调用一次（通常在用户注册时调用），用户登录前后的行为的关联建议在业务端实现。
在神策分析 1.13 版本之前，多次调用 TrackSignUp()时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。
更详细的说明请参考如何准确的标识用户，并在必要时联系我们的技术支持人员。

设置用户属性

为了更准确地提供针对人群的分析服务，神策分析 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() 接口将属性删除。

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

记录初次设定的属性

对于只在首次设置时有效的属性，我们可以使用 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);

数值类型的属性

对于数值型的用户属性，可以使用 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 );

列表类型的属性

对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 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);

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

// 此方法还有一个重载方法，方便处理只有一个值的情况
// 传入属性名称和需要插入属性的值，设置用户喜欢的电影属性（movies）
// 设置成功后 "movies" 属性值为 ["Dead Poets Society"]
sa.ProfileAppend(distinctId, "movies", "Dead Poets Society");

埋点事件采集

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

追踪事件

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

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

Sensors Analytics SDK 初始化成功后，可以通过 track() 记录事件，必须包含用户 ID（distinctId ）和事件名（eventName）这两个参数，同时可以传入一个 Dictionary<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);