Java SDK 快速接入

最后更新于:2019-11-18 08:57:44

在使用前,请先阅读数据模型的介绍。
更多参数接口信息介绍可前往 Java SDK 使用说明

1、事件设计表(示例)
2、集成 SDK
3、埋点示例
4、demo 示例

1. 事件设计表(示例)

事件设计表一般是由神策分析师和你们对接的同事,针对具体业务需求一起梳理的需要做埋点的 Excel 表。 神策分析系统宏观上有两张表,事件表(events)用于记录用户的行为事件,比如 注册、登录等;用户表(users)用于保存用户相关的一些信息,比如个人资料。

事件和用户属性设计
事件表 用户表
事件名 事件属性 数据类型 用户属性 数据类型
商品浏览( ViewProduct ) 商品 ID( ProductId ) 字符串(String) 用户等级属性( userLevel ) 字符串(String)
商品类别( ProductCatalog ) 字符串(String)
是否加入收藏夹( isAddedToFav ) 布尔(Boolean)

2. 集成 SDK

推荐使用Maven管理 Java 项目,在 pom.xml 文件中,添加以下依赖信息:

<dependencies>
  // ...
  <dependency>
    <groupId>com.sensorsdata.analytics.javasdk</groupId>
    <artifactId>SensorsAnalyticsSDK</artifactId>
    <version>3.1.11</version>
  </dependency>
</dependencies>

源码集成 sa-sdk-java

在程序中使用 ConcurrentLoggingConsumer 初始化 SensorsAnalytics 。 ConcurrentLoggingConsumer 用于将数据输出到指定目录并按天切割生成日志,并使用 LogAgent 工具进行实时导入,该工具能保证导入不重复、不遗漏。

// 使用 ConcurrentLoggingConsumer 初始化 SensorsAnalytics
// 例如将数据输出到 /data/sa 下的文件中,每天一个日志文件,以日期为后缀;例如 2018年5月21号当天的日志文件为: access.log.2018-05-21 
final SensorsAnalytics sa = new SensorsAnalytics(
        new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa/access.log"));

3. 埋点示例

3.1 追踪事件

SDK 初始化后,可以通过 track() 方法追踪用户行为事件,并为事件添加自定义属性(触发的事件会存储到神策分析系统的 events 表中)。

   // distinctId 当前用户的 ID
   // isLoginId 用户的 ID 是否是登录 ID,false 表示该 ID 是一个匿名 ID
   // eventName  事件名称
   // properties 事件的属性
  sa.track(distinctId, isLoginId, eventName, properties);

注意:当触发事件时的 ID 为登录 ID 时,isLoginId 参数必须指定为 true

例如:埋点 “ViewProduct” 事件,事件属性有商品 ID,商品类别,是否加入收藏夹。

// 用户的 Id
String distinctId = “ABCDEF123456789";
// 用户浏览商品
{
  Map<String, Object> properties = new HashMap<String, Object>();
  properties.put("ProductId", “123456");   // 商品 ID
  properties.put("ProductCatalog", "Laptop Computer”);   // 商品类别
  properties.put("isAddedToFav", true);  // 是否加入收藏夹,Boolean 类型的属性
  // 记录用户浏览商品事件
  sa.track(distinctId, true, "ViewProduct", properties);
}

3.2 设置用户属性

为了更准确地提供针对人群的分析服务,可以使用神策分析 SDK 的 profileSet() 等方法设置用户属性,如年龄、性别等。用户可以在留存分析、分布分析等功能中,使用用户属性作为过滤条件,精确分析特定人群的指标。 (设置的用户属性会存储到神策分析系统的 users 表中)

例如:设置用户的 “userLevel” 为 “VIP”。

String distinctId = "ABCDEF123456789";
Map<String, Object> properties = new HashMap<String, Object>();
// 设置用户等级属性(userLevel)为 VIP
properties.put("userLevel", "VIP");
sa.profileSet(distinctId, true, properties);

3.3 匿名 ID 和登录 ID 关联

如何准确的标识用户

成功关联设备 ID登录 ID 之后,用户在该设备 ID 上或该登录 ID 下的行为就会贯通,被认为是一个神策 ID 发生的。在进行事件、漏斗、留存等用户相关分析时也会算作一个用户。

关联设备 ID登录 ID 的方法虽然实现了更准确的用户追踪,但是也会增加埋点接入的复杂度。所以一般来说,我们建议只有当同时满足以下条件时,才考虑进行 ID 关联:

  1. 需要贯通一个用户在一个设备上注册前后的行为。
  2. 需要贯通一个注册用户在不同设备上登录之后的行为

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

    //  前端的匿名 ID
    String anonymousId = "9771C579-71F0-4650-8EE8-8999FA717761";

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

注意,trackSignUp() 建议在用户 注册/登录 时调用。在神策分析 1.13 版本之前,多次调用 trackSignUp() 时,只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 ID 关联的方法。更详细的说明请参考 如何准确的标识用户,并在必要时联系我们的技术支持人员。

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

  2. 如果 App 中嵌入了 iOS SDKAndroid SDK,需要客户端将匿名 ID 传给服务器端,然后获取到传过来的匿名 ID 。

4. Demo 示例

4.1

package com.sensorsdata.analytics.javasdk;

import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import org.apache.commons.logging.Log;

public class HelloSensorsAnalytics {    
    public static void main(String[] args) throws Exception {

    // 初始化 SensorsAnalytics
    final SensorsAnalytics sa = new SensorsAnalytics(
            new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa/access.log")); 


    String anonymousId = "JKER1232JKJFD7217"; // 用户未登录时,可以使用神策前端 SDK 生成的匿名 ID 来标识用户
    // 匿名状态下的浏览商品事件
    sa.track(anonymousId, false, "ViewProduct");


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



    Map<String, Object> properties = new HashMap<String, Object>();
    properties.clear();
    properties.put("$ip", "123.123.123.123"); //把 IP 传递给 SA,SA 会自动根据这个解析国家、省份、城市
    properties.put("ProductId", "123456"); // 商品 ID
    properties.put("ProductCatalog", "Laptop Computer");// 商品类别
    properties.put("isAddedToFav", true);  // 是否加入收藏夹,Boolean 类型的属性
    // 登录状态下的浏览具体商品事件
    sa.track(registerId, true, "viewProduct", properties);  


    sa.flush();  //发送缓存中的所有日志       
    }
}

生成的日志文件如下:

4.2
下载 LogAgent 文件,LogAgent 下载地址

4.3
检查运行环境(至少 Java 8 以上)

4.4
修改配置文件 logagent.conf,参考文档,需要注意的几个参数:logagent_id,path,pattern,project,host,port,token。

4.5
找到本地 LogAgent 目录,启动 LogAgent。默认每十秒发送一次数据,

注意打印信息的几个参数含义:

send speed: 1.200 records/sec:根据之前 10 秒处理情况计算的速度平均值;
reading file: /home/work/app/logs/service.log.2016-08-17:正在读取的文件路径;
key: (dev=fc01,ino=1197810):文件所在磁盘以及 inode;
offset: 122071 / 145071:第一个值是读取到文件中的位置,第二个值是正在读取的文件总大小。

4.6
此时再回到 Java 程序中,Run 一次代码,会看到,LogAgent 的打印信息变化。