全域用户关联 API（Java）

SDK 版本需要 >= v3.4.3

用户关联

用户注册/登录

调用接口后，会发送相关的绑定事件。对应的 key 和 value 不会缓存在本地，后续采集的事件，均不包含绑定的 ID 信息。

Java SDK

SensorsAnalyticsIdentity identity = SensorsAnalyticsIdentity.builder()
        .addIdentityProperty("$identity_mobile", "123")
		.addIdentityProperty("$identity_email", "a@a.com")
        .build();
sa.bind(identity);

JAVA

用户解绑

用户 ID 取消关联时调用，参数 key 为取消关联的 key，value 为对应的取消关联用户业务 ID。

调用接口后，会发送相关的解绑事件。

Java SDK

SensorsAnalyticsIdentity identity = SensorsAnalyticsIdentity.builder()
        .addIdentityProperty("$identity_mobile", "123")
        .build();
sa.unbind(identity);

JAVA

DistinctId 属性设置

在设置用户属性的时候，distinct_id 可以设置也可以不设置，若不设置，则以 identities 结构里面的用户维度标识顺序来作为 distinct_id;

sdk distinct_id 内部生成逻辑为：

若手动调用 setDistinctId() 方法，则 distinct_id 直接等于该处设置的值
若 identities 结构里面有 $identity_login_id ，则 distinct_id 取该维度标识的值
不满足上面的条件，则按顺序取 identities 里面标识 key+value ，并且长度不超过255个字符作为 distinct_id

用户属性

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

设置用户属性

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

String distinctId = "ABCDEF123456789"; 
IDMUserRecord userRecord = IDMUserRecord.starter()
        .setDistinctId(distinctId) //手动指定外层 distinct_id，这里参考 1.3 章节，可选项
        .addIdentityProperty(SensorsAnalyticsIdentity.LOGIN_ID, loginId) //用户维度标识
        .addIdentityProperty(SensorsAnalyticsIdentity.EMAIL, email)   //用户维度标识
        .addProperty("Sex", "Male") // 设置用户性别属性（Sex）为男性
        .addProperty("UserLv", "Elite VIP") // 设置用户等级属性（Level）为 VIP
        .build();
 sa.profileSetById(userRecord);

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

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

记录初次设定的属性

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

String loginId = "ABCDEF123456789"; 
IDMUserRecord userRecord = IDMUserRecord.starter()
        .addIdentityProperty(SensorsAnalyticsIdentity.LOGIN_ID, loginId) 
        .addProperty("AdSource", "App Store")
        .build();
sa.profileSetOnceById(userRecord);

列表类型的属性

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

String loginId = "ABCDEF123456789"; 

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

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

// 用户属性
Map<String, Object> properties = new HashMap<String, Object>();
properties.put("movies", movies);
properties.put("games", games);

// 传入properties，设置用户喜欢的电影属性（movies）和喜欢的游戏属性（games）
// 设置成功后，"movies" 属性值为 ["Sicario", "Love Letter"]；"games" 属性值为 ["Call of Duty", "Halo"]
IDMUserRecord userRecord = IDMUserRecord.starter()
        .addIdentityProperty(SensorsAnalyticsIdentity.LOGIN_ID, loginId)    
        .addProperty("movies", movies)
        .addProperty("games", games) 
         .build();
sa.profileAppendById(userRecord);

// 传入属性名称和需要插入属性的值，设置用户喜欢的电影属性（movies）
// 设置成功后 "movies" 属性值为 ["Sicario", "Love Letter", "Dead Poets Society"]
IDMUserRecord userRecord = IDMUserRecord.starter()
        .addIdentityProperty(SensorsAnalyticsIdentity.LOGIN_ID, loginId)    
        .addProperty("movies", "Dead Poets Society")
        .build();
sa.profileAppendById(userRecord);

埋点事件采集

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

追踪事件

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

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

神策分析 SDK 初始化成功后，可以通过 trackById() 记录事件，必须包含用户 ID、事件名（eventName）这三个参数，同时可以传入一个 IDMEventRecord 对象，为事件添加自定义事件属性。以电商产品为例，可以这样追踪一次购物行为：

// 使用 ConcurrentLoggingConsumer 初始化 SensorsAnalytics
final SensorsAnalytics sa = new SensorsAnalytics(new SensorsAnalytics.ConcurrentLoggingConsumer("您的日志文件路径"));

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

// 用户浏览商品
   
  IDMEventRecord eventRecord = IDMEventRecord.starter()
       .addIdentityProperty(SensorsAnalyticsIdentity.LOGIN_ID, distinctId) //用户维度标识
       .setEventName("ViewProduct") //设置埋点事件名称
       .addProperty("ProductId", "123456") // 设置埋点事件属性
       .build();
   sa.trackById(eventRecord); 


// 用户订单付款

	// 订单中的商品 ID 列表
    List<String> productIdList = new ArrayList<String>();
    productIdList.add("123456");
    productIdList.add("234567");
    productIdList.add("345678");
   IDMEventRecord eventRecord = IDMEventRecord.starter()
       .addIdentityProperty(SensorsAnalyticsIdentity.LOGIN_ID, distinctId) //用户维度标识
       .setEventName("PaidOrder") //设置埋点事件名称
       .addProperty("OrderId", "123456") // 设置埋点事件属性
       .addProperty("ProductIdList", productIdList)
       .build();
   sa.trackById(eventRecord);

通过调试模式，可以校验追踪的事件及属性是否正确。正常模式下，数据导入后，在神策分析中稍等片刻，便能看到追踪结果。