1. 用户关联

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

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

对于未注册的匿名用户，获取用户匿名 ID 的方法如下：

后端获取前端 JavaScript SDK 生成的匿名 ID 的方式：
可以在 Cookie 里面找到 key 为 sensorsdata2015jssdkcross 的 value 值然后进行 decodeURIComponent 解码，最后通过 JSON.parse 方法得到一个对象，对象里面的 distinct_id 的值即为所需要的 ID
(注意，如果前端已经调用过 login 方法，那么此时 distinct_id 为登录 ID，所以需要先获取 first_id 字段的值，如果获取不到，就去获取 distinct_id 的值)。
如果 App 中嵌入了 Login 方法，需要客户端使用神策提供的获取匿名 ID 接口，将匿名 ID 传给服务端，服务端使用客户端传过来的匿名 ID 作为 Distinct ID。

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

1.1. 用户注册/登录

通过 trackSignUp() 将匿名 ID 和登录 ID 关联，以保证用户分析的准确性。例如：

// 前端的匿名 ID,获取匿名 ID 的方式参考上文
String anonymousId = "9771C579-71F0-4650-8EE8-8999FA717761";

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

CODE

注意以下问题:

trackSignUp() 建议在用户注册/登录时调用。如果客户端也有采集任意事件，在注册/登录时，也需要在客户端调用一次关联方法 login() 将匿名 ID 和登录 ID 关联。注册/登录时，客户端和服务端都各自调用一次关联方法的原因如下：
- 一对一关联机制下，避免出现用户注册/登录时，客户端的关联信息 $SignUp 事件没有发送成功/延迟发送到神策系统，而服务端触发的事件( $is_login_id=true )先发送到神策系统中，导致登录 ID 自关联，从而导致登录 ID 无法再和匿名 ID 关联，客户端匿名行为和登录后的行为识别两个用户的行为。
- 客户端调用一次关联方法 login() 的作用，除了将匿名 ID 和登录 ID 关联之外，还会会将客户端标记用户的 distinctId 值从匿名 ID 切换为登录 ID。这样查看用户行为序列时，可以很好的根据 distinctId 的值判断用户行为是登录后的行为还是匿名行为。因此强烈建议用户登录/注册时，在客户端调用一次 login() 的同时，在服务端也调用一次 trackSignUp() 。
如果服务端只在用户登录成功之后，才会采集相关事件或者设置用户属性，要保证 track 事件/profileSet 设置用户属性（$is_login_id 设置为 true）的代码在 trackSignUp() 方法之后调用，从而可以保证先将匿名 ID 和登录 ID 关联之后，再采集登录用户的行为事件/设置用户属性。
在神策分析 1.13 版本之前，多次调用 trackSignUp() /login()时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 ID 关联的方法。更详细的说明请参考标识用户，并在必要时联系我们的技术支持人员。

2. 用户属性

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

2.1. 记录用户属性

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

String distinctId = "ABCDEF123456789";
UserRecord userRecord = UserRecord.builder().setDistinctId(distinctId).isLoginId(Boolean.TRUE)
        .addProperty("Sex", "Male") // 设置用户性别属性（Sex）为男性
        .build();
sa.profileSet(userRecord);

userRecord = UserRecord.builder().setDistinctId(distinctId).isLoginId(Boolean.TRUE)
        .addProperty("UserLv", "Elite VIP") // 设置用户等级属性（Level）为 VIP
        .build();
sa.profileSet(userRecord);

CODE

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

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

2.2. 记录初次设定的属性

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

String distinctId = "ABCDEF123456789";
UserRecord firstVisitRecord = UserRecord.builder().setDistinctId(distinctId).isLoginId(Boolean.TRUE)
        .addProperty("AdSource", "App Store")
        .build();
sa.profileSetOnce(firstVisitRecord);

CODE

2.3. 记录列表类型的属性

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

String distinctId = "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"]
UserRecord appendRecord = UserRecord.builder().setDistinctId(distinctId).isLoginId(Boolean.TRUE)
        .addProperty("movies", movies)
        .addProperty("games", games)
        .build();
sa.profileAppend(appendRecord);

// 传入属性名称和需要插入属性的值，设置用户喜欢的电影属性（movies）
// 设置成功后 "movies" 属性值为 ["Sicario", "Love Letter", "Dead Poets Society"]
UserRecord appendRecord = UserRecord.builder().setDistinctId(distinctId).isLoginId(Boolean.TRUE)
        .addProperty("movies", "Dead Poets Society")
        .build();
sa.profileAppend(appendRecord);

CODE

3. 埋点事件采集

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

3.1. 追踪事件

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

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

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

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

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

// 用户浏览商品
{
     EventRecord lookRecord = EventRecord.builder().setDistinctId(distinctId).isLoginId(Boolean.FALSE)
           .setEventName("ViewProduct")
           .addProperty("$time", new Date())  // '$time' 属性是系统预置属性，表示事件发生的时间，如果不填入该属性，则默认使用系统当前时间
           // '$ip' 属性是系统预置属性，如果服务端中能获取用户 IP 地址，并填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息
          .addProperty("$ip", "123.123.123.123")
          .addProperty("ProductId", "123456")
          .build();
    // 记录用户浏览商品事件
    sa.track(lookRecord);
}

// 用户订单付款
{
	// 订单中的商品 ID 列表
    List<String> productIdList = new ArrayList<String>();
    productIdList.add("123456");
    productIdList.add("234567");
    productIdList.add("345678");
    EventRecord lookRecord = EventRecord.builder().setDistinctId(distinctId).isLoginId(Boolean.FALSE)
           .setEventName("PaidOrder")
           // '$ip' 属性是系统预置属性，如果服务端中能获取用户 IP 地址，并填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息
           .addProperty("$ip", "123.123.123.123")
           .addProperty("OrderId", "123456")
           .addProperty("ProductIdList", productIdList)
           .build();
    // 记录用户订单付款事件
    sa.track(lookRecord);
}

CODE

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