1. 用户关联

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

2. 用户属性

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

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

3. 埋点事件采集

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

3.1. 追踪事件

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

3.2. 物品元数据上报

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

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

3.2.1. 设置物品

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

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

public void itemSet(String itemType, String itemId, Map<String, Object> properties);

// 例如
Map<String, Object> properties = new LinkedHashMap<>();
properties.put("name", "C++ Primer");
properties.put("price", 31.54);
sensorsAnalytics.itemSet("book", "0321714113", properties);

CODE

3.2.2. 删除一个物品

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

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

public void itemDelete(String itemType, String itemId, Map<String, Object> properties);

// 例如
ItemRecord deleteRecord = ItemRecord.builder().setItemId("0321714113").setItemType("book")
        .build();
sensorsAnalytics.itemDelete(deleteRecord);

CODE

4. 事件属性

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

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

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

4.1. 系统预置属性

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

$ip - 填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息，该属性值为 String 类型；
$time - 填入该属性，神策分析将事件时间设置为属性值的时间，该属性值必须为 Date 类型。请注意，神策分析默认会过滤忽略 2 年前或 1 小时后的数据，如需修改请联系我们；
$project - 填入该属性，神策分析某些导入工具例如 LogAgent （LogAgent 的配置中未指定 project 参数时）会将数据导入指定项目。

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

4.2. 事件公共属性

特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 registerSuperProperties() 将该属性设置为事件公共属性。例如将服务器的应用版本及机房地址设置为事件的公共属性，设置方法如下:

//设置公共属性,以后上传的每一个事件都附带该属性
SuperPropertiesRecord propertiesRecord = SuperPropertiesRecord.builder()
        .addProperty("ServerVersion", "1.2")
        .addProperty("Location", "Beijing")
        .build();
sa.registerSuperProperties(propertiesRecord);

CODE

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

String distinctId = "ABCDEF123456789";
EventRecord loginRecord = EventRecord.builder().setDistinctId(distinctId).isLoginId(Boolean.FALSE)
        .setEventName("UserLogin")
        .addProperty("$ip", "123.123.123.123")
        .build();
// 追踪用户登录事件
sa.track(loginRecord);

CODE

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

String distinctId = "ABCDEF123456789";
EventRecord loginRecord = EventRecord.builder().setDistinctId(distinctId).isLoginId(Boolean.FALSE)
        .setEventName("UserLogin")
        .addProperty("$ip", "123.123.123.123")
        .addProperty("ServerVersion", "1.2")
        .addProperty("Location", "Beijing")
        .build();
// 追踪用户登录事件
sa.track(loginRecord);

CODE

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

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

5. 其他功能

5.1. 即时事件采集

在 Java SDK 中目前仅 BatchConsumer 和 FastBatchConsumer 支持即时事件采集上报，用于即时营销的业务场景。

// 在 BatchConsumer 初始化时设置即时事件名称集合 "test1", "test2"
BatchConsumer bc = new BatchConsumer("从神策分析获取的数据接收的 URL", 50, 0, true, 3, Arrays.asList("test1", "test2"));

// 在 FastBatchConsumer 初始化时设置即时事件名称集合 "test1", "test2"
FastBatchConsumer bc = new FastBatchConsumer(HttpClients.custom(), "从神策分析获取的数据接收的 URL",
    false , 50, 0, 3, 3,  new Callback() {
  @Override
  public void onFailed(FailedData failedData) {
    SensorsLogsUtil.setFailedData(failedData);
  }
}, Arrays.asList("test1", "test2"));

JAVA

该接口适用于即时营销的业务场景，其它业务设置无实际意义。Java SDK，考虑到后端数据量非常大，事件上报有以下特点：

「即将进入缓存的事件」与「缓存中的事件」类型不一致，会立即上报缓存中的所有事件；
如果需要立即上报即时事件，track 之后，需要主动调用 flush 方法。