Java SDK

Java SDK 主要用于服务端 Java 应用

集成卓尔数科智能分析SDK

 直接从 GitHub 下载 Java SDK 的源代码，并将其作为模块添加进项目中使用；

初始化卓尔数科智能分析 SDK

在程序启动时（如 public static void main(String[] args) 方法中），调用构造函数 new ZallDataAnalytics(Consumer) 初始化 Java SDK 实例。

 public static void main(String[] args) {
     // 上报数据的url
     final String serverUrl = "http://${ip}:${port}/a?project=${project}&service=${service}";
     
     // 当缓存的数据量达到80条时，批量发送数据
     final int bulkSize = 80;
     
     // 使用 BatchConsumer 初始化 ZallDataAnalytics
     final ZallDataAnalytics za = new ZallDataAnalytics(new BatchConsumer(serverUrl, bulkSize));
 ​
     // 用户的 Distinct ID
     String distinctId = "abcdefgABCDEFG123456789";
 ​
     // 记录用户登录事件
     za.track(distinctId, true, "UserLogin");
 ​
     // 使用卓尔数科智能分析记录用户行为数据
     // ... 
 }
 ​

用户识别

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

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

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

  1. 后端获取前端 JavaScript SDK 生成的匿名 ID 的方式： 可以在 Cookie 里面找到 key 为 zalldatajssdkcross 的 value 值然后进行 decodeURIComponent 解码，最后通过 JSON.parse 方法得到一个对象，对象里面的 distinct_id 的值即为所需要的 ID (注意，如果前端已经调用过 login 方法，那么此时 distinct_id 为登录 ID，所以需要先获取 first_id 字段的值，如果获取不到，就去获取 distinct_id 的值)。

  2. 如果 App 中嵌入了 Login 方法，需要客户端提供获取匿名 ID 接口，将匿名 ID 传给服务端，服务端使用客户端传过来的匿名 ID 作为 Distinct ID。

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

用户注册/登录

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

注意以下问题:

  • trackSignUp()

    建议在用户注册/登录时调用。如果客户端也有采集任意事件，在注册/登录时，也需要在客户端调用一次关联方法 login() 将匿名 ID 和登录 ID 关联。 注册/登录时，客户端和服务端都各自调用一次关联方法的原因如下：

    • 一对一关联机制下，避免出现用户注册/登录时，客户端的关联信息 事件没有发送成功延迟发送到分析系统，而服务端触发的事件​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 关联之后，再采集登录用户的行为事件/设置用户属性。对于不清楚关联关系时，在必要时联系我们的技术支持人员。

追踪事件

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

  • 图片社交产品，可以追踪用户浏览图片和评论事件

  • 电商产品，可以追踪用户注册、浏览商品和下订单等事件

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

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

事件属性

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

  • 事件属性是一个 Map 对象；

  • Map 中每个元素描述一个属性，Key 为属性名称，必需是 String 类型；

  • Map 中，每个元素的 Value 是属性的值，支持 String、Boolean、Number、List 和 Date。

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

系统预置属性

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

  • $ip - 填入该属性，智能分析会自动根据 IP 地址解析用户的省份、城市信息，该属性值为 String 类型；

  • $time - 填入该属性，智能分析将事件时间设置为属性值的时间，该属性值必须为 Date 类型。请注意，智能分析默认会过滤忽略 2 年前或 1 小时后的数据，如需修改请联系我们；

  • $project - 填入该属性，智能分析某些导入工具例如 LogAgent （LogAgent 的配置中未指定 project 参数时）会将数据导入指定项目。

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

事件公共属性

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

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

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

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

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

设置用户属性

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

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

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

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

记录初次设定的属性

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

数值类型的属性

对于数值型的用户属性，可以使用 profileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：

列表类型的属性

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

物品元数据上报

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

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

设置物品

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

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

删除一个物品

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

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

立刻上报缓存数据

如果想要事件数据、用户数据或者物品数据立刻上报，可以调用 flush() 方法：

设置智能分析 SDK

以下内容说明如何更精细地控制智能分析 SDK 的行为。

数据采集

Java SDK 主要由以下两个组件构成:

  • ZallDataAnalytics: 用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例

  • Consumer: Consumer 会进行实际的数据发送

为了让开发者更灵活的接入数据，智能分析 SDK 实现了以下 Consumer。

DebugConsumer

用于校验数据导入是否正确，关于调试模式的详细信息，请进入相关页面查看。

请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。

线上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。

BatchConsumer

批量发送数据的 Consumer，当数据达到指定的量时（默认80条，最多可指定1000条），才将数据进行发送。也可以调用 flush() 方法去强制发送。

通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任何线上服务中。

ConsoleConsumer

用于将数据输出到特定 Writer，一般用于在生产环境的 Java 程序中处理历史数据，生成日志文件并使用 BatchImporter 等工具导入

LoggerConsumer

批量实时写本地文件，文件以天为分隔，需要搭配 LogBus 进行上传，logDirectory为写入本地的文件夹地址，您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

如果您想按小时切分文件，您可以初始化代码如下：

如果您想按大小切分，您可以初始化代码如下：

关闭 SDK

如果您想要主动关闭 SDK，可以参考以下使用方式：

其它设置

导入历史数据：默认情况下，会过滤发生时间比较久远数据（例如 10 天之前，具体取决于服务端设置），如果想导入历史数据，可以通过开启 Time Free 选项来绕过这个限制。

上一页服务端SDK

最后更新于

这有帮助吗？