全域用户关联 API（C#）
|
收藏
SDK 版本需要 >= v2.1.0
1. 用户关联
1.1. 用户注册/登录
在全域用户关联业务中，用户标识通过 Bind 接口进行绑定。用户登录时调用 Bind() 绑定，第一个参数从详细的预置 id key 列表中获取，第二个参数为对应的具体用户 ID。例如，给用户（"ABCDEF123456789"）绑定手机号：
接口说明：
/// <summary>
/// 绑定用户标识
/// </summary>
/// <param name="identities">用户标识 List，至少需要两个 identity</param>
public void Bind(List<SensorsAnalyticsIdentity> identities)
C#
使用示例：
List<SensorsAnalyticsIdentity> identities = SensorsAnalyticsIdentityHelper.CreateBuilder()
.AddIdentityProperty("$identity_mobile", "123")
.AddIdentityProperty("$identity_email", "a@a.com")
.Build();
sa.bind(identities)
C#
1.2. 用户解绑
多用户 ID 取消关联时调用 UnBind() 解绑，第一个参数为取消关联的 key，第二个参数为对应的取消关联用户 ID。
接口说明：
/// <summary>
/// 解绑用户标识
/// </summary>
/// <param name="identity">用户标识</param>
public void Unbind(SensorsAnalyticsIdentity identity)
C#
使用示例：
SensorsAnalyticsIdentity identity = new SensorsAnalyticsIdentity("$identity_mobile", "123")
sa.unbind(identity);
C#
2. 设置用户属性
为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为过滤条件或以用户属性作为维度进行多维分析。
2.1. 记录用户属性
使用 ProfileSetById() 设置用户属性：
接口说明：
/// <summary>
/// 设置用户的属性。如果要设置的 properties 的 key，之前在这个用户的 profile 中已经存在，则覆盖，否则，新创建
/// </summary>
/// <param name="identities">用户标识 List</param>
/// <param name="properties">用户属性</param>
public void ProfileSetById(List<SensorsAnalyticsIdentity> identities, Dictionary<String, Object> properties)
/// <summary>
/// 设置用户的属性。如果要设置的 properties 的 key，之前在这个用户的 profile 中已经存在，则覆盖，否则，新创建
/// </summary>
/// <param name="identity">用户标识</param>
/// <param name="properties">用户属性</param>
public void ProfileSetById(SensorsAnalyticsIdentity identity, Dictionary<String, Object> properties)
C#
示例示例：
//1. 用户匿名访问网站，cookieId 默认神策生成分配
String cookieId = "ABCDEF123456789";
SensorsAnalyticsIdentity identity = new SensorsAnalyticsIdentity("cookieId", cookieId);
//2.用户注册时，填充了一些个人信息，可以用Profile接口记录下来
Dictionary<string, Object> userRecord = new Dictionary<string, object>();
userRecord.Add("$city", "武汉");
userRecord.Add("$province", "湖北");
userRecord.Add("$name", "昵称123");
userRecord.Add("$signup_time", DateTime.Now);
userRecord.Add("Gender", "male");
userRecord.Add("age", 20);
sa.ProfileSetById(identity, userRecord);
C#
对于不再需要的用户属性，可以通过 ProfileUnsetById() 接口将属性删除。用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。
2.2. 记录初次设定的属性
对于只在首次设置时有效的属性，我们可以使用 ProfileSetOnceById() 记录这些属性。与 ProfileSetById() 接口不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，ProfileSetOnceById() 比较适用于为用户设置首次激活时间、首次注册时间等属性。
接口说明：
/// <summary>
/// 首次设置用户的属性。与 ProfileSetById 接口不同的是：如果要设置的 properties 的 key，在这个用户的 profile 中已经存在，则不处理，否则，新创建
/// </summary>
/// <param name="identities">用户标识 List</param>
/// <param name="properties">用户属性</param>
public void ProfileSetOnceById(List<SensorsAnalyticsIdentity> identities, Dictionary<String, Object> properties)
/// <summary>
/// 首次设置用户的属性。与 ProfileSetById 接口不同的是：如果要设置的 properties 的 key，在这个用户的 profile 中已经存在，则不处理，否则，新创建
/// </summary>
/// <param name="identity">用户标识</param>
/// <param name="properties">用户属性</param>
public void ProfileSetOnceById(SensorsAnalyticsIdentity identity, Dictionary<String, Object> properties)
C#
示例示例：
//1. 用户匿名访问网站，cookieId 默认神策生成分配
String cookieId = "ABCDEF123456789";
SensorsAnalyticsIdentity identity = new SensorsAnalyticsIdentity("cookieId", cookieId);
//2.设置首次访问时间
Dictionary<string, Object> firstVisitRecord = new Dictionary<string, object>();
firstVisitRecord.Add("$first_visit_time", DateTime.Now);
// $is_login_id 属性判断 distinct_id 是否为登录 ID，如果是则设置为 true，否则为 false，默认为 false
firstVisitRecord.Add("$is_login_id", true);
sa.ProfileSetOnceById(identity, firstVisitRecord);
C#
2.3. 数值类型的属性
对于数值型的用户属性，可以使用 ProfileIncrementById() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。
接口说明：
/// <summary>
/// 为用户的一个或多个数值类型的属性累加一个数值，若该属性不存在，则创建它并设置默认值为0。属性取值只接受Number类型
/// </summary>
/// <param name="identities">用户标识 List</param>
/// <param name="properties">用户属性</param>
public void ProfileIncrementById(List<SensorsAnalyticsIdentity> identities, Dictionary<String, Object> properties)
/// <summary>
/// 为用户的一个或多个数值类型的属性累加一个数值，若该属性不存在，则创建它并设置默认值为0。属性取值只接受Number类型
/// </summary>
/// <param name="identity">用户标识</param>
/// <param name="properties">用户属性</param>
public void ProfileIncrementById(SensorsAnalyticsIdentity identity, Dictionary<String, Object> properties)
/// <summary>
/// 为用户的数值类型的属性累加一个数值，若该属性不存在，则创建它并设置默认值为0
/// </summary>
/// <param name="identities">用户标识 List</param>
/// <param name="property">属性名称</param>
/// <param name="value">属性值</param>
public void ProfileIncrementById(List<SensorsAnalyticsIdentity> identities, String property, long value)
/// <summary>
/// 为用户的数值类型的属性累加一个数值，若该属性不存在，则创建它并设置默认值为0
/// </summary>
/// <param name="identity">用户标识</param>
/// <param name="property">属性名称</param>
/// <param name="value">属性值</param>
public void ProfileIncrementById(SensorsAnalyticsIdentity identity, String property, long value)
C#
使用示例：
//1. 用户匿名访问网站，cookieId 默认神策生成分配
String cookieId = "ABCDEF123456789";
SensorsAnalyticsIdentity identity = new SensorsAnalyticsIdentity("cookieId", cookieId);
//2.给属性加值
Dictionary<string, Object> incrementRecord = new Dictionary<string, object>();
incrementRecord.Add("age", 2);
sa.ProfileIncrementById(identity, incrementRecord);
C#
2.4. 列表类型的属性
对于用户喜爱的电影、用户点评过的餐厅、兴趣爱好等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 string 类型，且元素的值会自动去重。关于列表类型限制请见 数据格式 属性长度限制。
接口说明：
/// <summary>
/// 为用户的一个或多个数组类型的属性追加字符串.
/// </summary>
/// <param name="identities">用户标识 List</param>
/// <param name="properties">用户属性</param>
public void ProfileAppendById(List<SensorsAnalyticsIdentity> identities, Dictionary<String, Object> properties)
/// <summary>
/// 为用户的一个或多个数组类型的属性追加字符串.
/// </summary>
/// <param name="identity">用户标识</param>
/// <param name="properties">用户属性</param>
public void ProfileAppendById(SensorsAnalyticsIdentity identity, Dictionary<String, Object> properties)
C#
使用示例：
//1.用户匿名访问网站，cookieId 默认神策生成分配
String cookieId = "ABCDEF123456789";
SensorsAnalyticsIdentity identity = new SensorsAnalyticsIdentity("cookieId", cookieId);
//2.追加属性，这里追加兴趣爱好
List<String> newInterest = new List<String>();
newInterest.Add("ball");
Dictionary<string, Object> appendRecord = new Dictionary<string, object>();
appendRecord.Add("interest", newInterest);
sa.ProfileAppendById(identity, appendRecord);
C#
3. 埋点事件采集
在 SDK 初始化完成之后，您可以通过以下接口进行数据埋点。
3.1. 追踪事件
第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：
- 图片社交产品，可以追踪用户浏览图片和评论事件
- 电商产品，可以追踪用户注册、浏览商品和下订单等事件
用户通过 TrackById() 接口记录事件，对于任何事件，必须包含用户标志符（Identity）和事件名（event）两个参数。用户可以在 TrackById() 的第三个参数传入一个 map[string]interface{} 对象，为事件添加自定义事件属性。以电商产品为例，可以这样追踪一次购物行为：
接口说明：
/// <summary>
/// 使用用户标识 3.0 方式进行时间埋点
/// </summary>
/// <param name="identity">用户标识</param>
/// <param name="eventName">事件名</param>
/// <param name="properties">事件属性</param>
public void TrackById(SensorsAnalyticsIdentity identity, String eventName, Dictionary<String, Object> properties)
C#
使用示例：
//1.用户匿名访问网站，cookieId 默认神策生成分配
String cookieId = "ABCDEF123456789";
SensorsAnalyticsIdentity identity = new SensorsAnalyticsIdentity("cookieId", cookieId);
//2.搜索商品
Dictionary<string, Object> searchRecord = new Dictionary<string, object>();
searchRecord.Add("KeyWord", "XX手机");
sa.TrackById(identity, "SearchProduct", searchRecord);
//3.浏览商品
Dictionary<string, Object> lookRecord = new Dictionary<string, object>();
lookRecord.Add("ProductName", "XX手机");
lookRecord.Add("ProductType", "智能手机");
lookRecord.Add("ShopName", "XX官方旗舰店");
sa.TrackById(identity, "ViewProduct", lookRecord);
C#
注：本文档内容为神策产品使用和技术细节说明文档，不包含适销类条款；具体企业采购产品和技术服务内容，以商业采购合同为准。
