JAVA SDK

版本记录

版本	说明	日期
1.0.16-cdp	1.支持非用户主体事件上报 2.用户属性事件和维度表事件属性支持map类型	2024-09-24
1.0.14-cdp	1.维度表支持列表属性 2.支持埋点事件预置属性	2023-08-11
1.0.13-cdp	1.修复initConfig不生效 2.升级pb版本为3.27.1	2023-03-27
1.0.12-cdp	支持埋点事件事件变量、用户变量可传列表类型	2022-04-20
1.0.11-cdp	支持埋点事件可传eventTime参数	2022-04-02
1.0.10-cdp	支持最近测量协议	2021-11-08
1.0.9-cdp	1. 支持userKey字段设置 2. 支持设置访问用户ID	2022-02-11

简介

Java SDK 源码托管在 growingio/growingio-java-sdk

GrowingIO提供在Server端部署的SDK，从而可以方便的进行事件上报等操作。

支持 java 7+, 如需支持java 6参见支持 Java 6 版本环境

info

Java SDK从1.0.10-cdp版本开始使用v3协议进行事件上报, 使用前确认平台版本支持v3协议

支持的平台版本为 OP-13.6、OP-14.x、OP-2.x 版本

集成准备

获取SDK初始化必传参数：AccountID、DataSourceID、Host

info

AccountID：项目ID，代表一个项目
DataSourceID：数据源ID，代表一个数据源
Host：采集数据上报的服务器地址，非平台地址

AccountID、DataSourceID 需要在CDP增长平台上新建数据源，或从已创建的数据源中获取, 如不清楚或无权限请联系您的专属项目经理或技术支持

创建

查看

依赖

我们推荐使用 Maven 管理Java 项目，请在 pom.xml 文件中，添加一下依赖信息，Maven将自动获取 Java SDK 并更新项目配置

pom.xml

<dependencies>
    <dependency>
        <groupId>io.growing.sdk.java</groupId>
        <artifactId>growingio-java-sdk</artifactId>
        <version>1.0.16-cdp</version>
    </dependency>
</dependencies>

若出现依赖冲突的问题（例如运行时找不到类），可以选择使用 standalone

<dependency>
    <groupId>io.growing.sdk.java</groupId>
    <artifactId>growingio-java-sdk</artifactId>
    <version>1.0.16-cdp</version>
    <classifier>standalone</classifier>
    <exclusions>
        <exclusion>
            <groupId>com.google.protobuf</groupId>
            <artifactId>protobuf-java</artifactId>
        </exclusion>
    </exclusions>
</dependency>

如果使用gradle依赖，可以使用如下集成方式

implementation 'io.growing.sdk.java:growingio-java-sdk:1.0.16-cdp'

若出现依赖冲突的问题（例如运行时找不到类），可以选择使用 standalone

implementation('io.growing.sdk.java:growingio-java-sdk:1.0.16-cdp:standalone') {
    exclude module: 'protobuf-java'
}

配置文件信息

配置在资源目录 resources/gio.properties

#项目采集端地址, https://api.growingio.com 需要填写完整的url地址, 如不清楚请联系您的专属项目经理
api.host=Your ServerHost
#项目的AccountID
project.id=填写您项目的AccountID
#消息发送间隔时间,单位ms（默认 100）
send.msg.interval=100
#消息发送线程数量 （默认 3）
send.msg.thread=3
#消息队列大小 （默认 500）
msg.store.queue.size=500
#日志级别输出 (debug | error)
logger.level=debug
#自定义日志输出实现类
logger.implemention=io.growing.sdk.java.logger.GioLoggerImpl
#运行模式，test:仅输出消息体，不发送消息，production: 发送消息
run.mode=test
# 设置代理, 如果不设置，默认为不使用代理
# proxy.host=127.0.0.1
# proxy.port=3128
# 设置代理认证用户密码, 如果不设置，默认为不使用用户验证 [认证加密方式为 Basic base64]
# proxy.user=demo
# proxy.password=demo
#http 连接超时时间,默认2秒
#connection.timeout=2000
#http 连接读取时间,默认2秒
#read.timeout=2000
# 带拒绝策略的发送策略，默认不采用，此策略在队列快满时打印出debug日志，并且会使用新的线程（个数同send.msg.thread）加速消费队列元素
# 但可能仍然消费速度不够，导致抛出GIOSendBeRejectedException异常，为了保险起见，使用者应当捕获该异常。
# 并且此策略新增了shutdownAwait方法关联了队列状态和JVM关闭钩子，此举旨在防止主线程关闭时，内存队列未消费的元素丢失。
# msg.store.strategy=abortPolicy
# 队列负载率，当为0.5时，表明，队列中元素达到一半时，会出现debug日志，并会使用新线程加速消费队列。队列负载降低到0.5以下后，恢复
# 此值越大，队列越接近满状态，加速线程执行的时间越提前。"加速"可能对接口接收服务造成压力，谨慎使用！
# msg.store.queue.load_factor=0.5

注意

请按照您的项目情况修改api.host 和 project.id。
run.mode 表示运行模式。当值为 test 时，仅输出消息体，不发送采集数据；当值为 production 时，才向发送采集数据。

事件消息

默认采用阻塞队列，队列大小为500.
如果队列满了，新的消息会被丢弃（可通过 msg.store.queue.size 和 send.msg.interval 调节队列大小和消息发送间隔时间，避免丢消息）

代码示例

// Config GrowingIO
// 参数需要从CDP增长平台上，创建新应用，或从已创建的数据源中获取, 如不清楚请联系您的专属项目经理
// YourAccountId eg: 0a1b4118dd954ec3bcc69da5138bdb96
// YourDatasourceId eg: 11223344aabbcc
private static GrowingAPI project = new GrowingAPI.Builder().setProjectKey("your accountId").setDataSourceId("your dataSourceId").build();

//事件行为消息体，anonymousId 和 loginUserId 参数，不能同时为空
GioCdpEventMessage eventMessage = new GioCdpEventMessage.Builder()
    .eventTime(System.currentTimeMillis())            // 默认为系统当前时间 (选填)
    .eventKey("3")                                    // 埋点事件标识 (必填)
    .eventNumValue(1.0)                               // 打点事件数值 (选填), 已废弃
    .anonymousId("device_id")                         // 访问用户ID (选填)
    .loginUserKey("account")                          // 登录用户KEY (选填，需有规划并在平台配置后再上报)
    .loginUserId("417abcabcabcbac")                   // 登陆用户ID (选填)
    .addEventVariable("product_name", "苹果")          // 事件属性 (选填)
    .addEventVariable("product_classify", "水果")      // 事件属性 (选填)
    .addEventVariable("product_price", 14)            // 事件属性 (选填)
    .addItem("item_id", "item_key")                   // 物品模型ID, KEY (选填)
    .build();

//上传事件行为消息到服务器
project.send(eventMessage);

API说明

设置项目信息

参数说明

参数名称	类型	是否必填	说明
setProjectKey	string	是	项目ID
setDataSourceId	string	是	数据源ID

// Config GrowingIO
// 参数需要从CDP增长平台上，创建新应用，或从已创建的数据源中获取, 如不清楚请联系您的专属项目经理
// YourAccountId eg: 0a1b4118dd954ec3bcc69da5138bdb96
// YourDatasourceId eg: 11223344aabbcc
private static GrowingAPI project = new GrowingAPI.Builder().setProjectKey("your accountId").setDataSourceId("your dataSourceId").build();

埋点事件

发送一个埋点事件。在添加发送的埋点事件代码之前，需在CDP平台事件管理界面创建埋点事件以及关联事件属性。

info

当需要标记用户ID类型时，请先进行规划，并在平台的数据中心，添加新的用户身份类型，再设置userkey，误设会影响数据质量。

参数说明

参数名称	类型	是否必填	说明
eventTime	long	否	事件发生时间(毫秒)；需要开启“自定义event_time上报”功能方可生效，请联系技术支持确认（仅支持OP版本，SaaS版本暂不支持）
eventKey	string	是	埋点事件标识
domain	string	否	APP包名或H5域名
urlScheme	string	否	链接协议
deviceBrand	string	否	设备品牌
deviceModel	string	否	设备型号
deviceType	string	否	设备类型（只能为PHONE/PAD）
appVersion	string	否	App版本
appName	string	否	App名称
language	string	否	语言，ISO 639标准
anonymousId	string	否	访问用户ID，与登录用户ID，不能同时为空
loginUserKey	string	否	登录用户KEY，传此参数时，同时需传登录用户ID
loginUserId	string	否	登录用户ID，与访问用户ID，不能同时为空
addEventVariable	(string, object)	否	事件发生时所伴随的属性信息； object支持 string\|double\|int\|List,List 中元素支持string\|double\|int；当事件属性关联有维度表时，属性值为对应的维度表模型ID(记录ID)
addEventVariables	map<string, object>	否	事件属性集合； object支持 string\|double\|int\|List,List 中元素支持string\|double\|int；当事件属性关联有维度表时，属性值为对应的维度表模型ID(记录ID)
addItem	(string, string)	否	物品模型ID, 物品模型Key

代码示例

// anonymousId 和 loginUserId 参数，不能同时为空
GioCdpEventMessage msg = new GioCdpEventMessage.Builder()
                    .eventTime(System.currentTimeMillis())            // 默认为系统当前时间 (选填)
                    .eventKey("eventKey")                             // 事件标识 (必填)
                    .domain("com.growingio.app")                      // App包名或H5域名（选填）
                    .urlScheme("growing.123c12fb12f123cc")            // 链接协议（选填）
                    .deviceBrand("google")                            // 设备品牌（选填）
                    .deviceModel("Nexus 5")                           // 设备型号（选填）
                    .deviceType("PHONE")                              // 设备类型（选填）
                    .appVersion("1.2.4")                              // App版本（选填）
                    .appName("看数助手")                               // App名称（选填）
                    .language("zh_CN")                                // 语言（选填）
                    .anonymousId("device_id")                         // 访问用户ID (选填)
                    .loginUserKey("account")  // 登录用户KEY (选填，需有规划并在平台配置后再上报)
                    .loginUserId("417abcabcabcbac")                   // 登录用户ID (选填)
                    .addEventVariable("product_name", "cdp苹果")       // 事件属性 (选填)
                    .addEventVariable("product_classify", Arrays.asList("苹果", "香蕉"))       // 事件属性 (选填)
                    .addEventVariables(map)                           // 事件属性集合 (选填)
                    .addItem("itemId", "itemKey")                     // 物品模型ID, KEY (选填)
                    .build();

// 非用户主体事件，访问用户ID和登录用户ID可不设置，需要指定登录用户key为指定值
GioCdpEventMessage msg = new GioCdpEventMessage.Builder()
                .eventKey("payOrder")
                .loginUserKey(GioCdpEventMessage.XEI_USER_KEY)
                .addEventVariable("prod_id", "0001")
                .addEventVariable("money", "15.52")
                .build()

info

详细使用示例:埋点事件示例

登录用户属性事件

以登录用户的身份定义登录用户属性，比如年龄、性别、会员等级等，用于用户信息相关分析。
在添加登录用户属性代码之前，需要在CDP平台用户管理界面中创建用户属性

info

当需要标记用户ID类型时，请先进行规划，并在平台的数据中心，添加新的用户身份类型，再设置userkey，误设会影响数据质量。

参数说明

参数名称	类型	是否必填	说明
time	long	否	事件发生时间(毫秒)
anonymousId	string	否	访问用户ID，与登录用户ID，不能同时为空
loginUserKey	string	否	登录用户KEY，传此参数时，同时需传登录用户ID
loginUserId	string	是	登录用户ID，与访问用户ID，不能同时为空
addUserVariable	(string, object)	否	登录用户属性； object支持 string\|double\|int\|List,List中元素支持string\|double\|int
addUserVariables	map<string, object>	否	登录用户属性集合； object支持 string\|double\|int\|List,List 中元素支持string\|double\|int
addUserVariables	(string, map<string, string>)	否	登录用户属性, 支持单层map类型

代码示例

// anonymousId 和 loginUserId 参数，不能同时为空
GioCdpUserMessage msg = new GioCdpUserMessage.Builder()
                .time(System.currentTimeMillis())      // 默认为系统当前时间 (选填)
                .anonymousId("device_id")              // 访问用户ID (选填)
                .loginUserKey("account")    // 登录用户KEY (选填，需有规划并在平台配置后再上报)
                .loginUserId("loginUserId")            // 登录用户ID的 (选填)
                .addUserVariable("gender", "man")      // 登录用户属性 (选填)
                .addUserVariable("education", Arrays.asList("本科", "硕士"))      // 登录用户属性 (选填)
                .addUserVariables(map)                 // 登录用户属性集合 (选填)
                .addUserVariables('certificates', map)        // 登录用户属性, 支持单层map类型
                .build();

info

详细使用示例:用户属性事件示例

维度表

上传一个维度表记录。在添加所需要上传维度表记录代码之前，需要在维度表管理界面中创建对应维度表及其属性

参数说明

参数名称	类型	是否必填	说明
id	string	是	维度表模型ID(记录ID)
key	string	是	维度表标识符
addItemVariable	map<string, string>	否	维度表属性及值；多个属性可调用多次

代码示例

GioCdpItemMessage msg = new GioCdpItemMessage.Builder()
                .id("1001")                        // 维度表模型ID(记录ID) (必填)
                .key("product")                    // 维度表标识符 (必填)
                .addItemVariable("color", "red")   // 维度表属性 (选填)
                .build();

用户融合

可将不同类型的登录用户ID识别为一个登录用户

参数说明

参数名称	类型	是否必填	说明
addIdentities	(string, string)	否	用户KEY, 用户ID
addIdentities	map<string, string>	否	(用户KEY, 用户ID)集合

代码示例

GioCdpUserMappingMessage msg = new GioCdpUserMappingMessage.Builder()
        .addIdentities("phone", "1**********1")          // 登录用户KEY, 登录用户ID
        .addIdentities("email", "2********0@qq.com")     // 登录用户KEY, 登录用户ID
        .addIdentities(map)
        .build();

程序测试

请按照如下步骤进行埋点数据的开发联调。

完成埋点事件的配置

在GrowingIO【数据】>【数据管理】中创建埋点事件及事件属性/登录用户属性，如图所示。 custom data

测试程序配置

在您的Java项目中的pom.xml中增加GrowingIO Java SDK的依赖（首次集成需要）
在gio.properties配置文件将run.mode定义为test
在您的Java项目中找到合适的埋点位置，调用埋点事件API/登录用户属性API上传数据
在输出的日志中查找是否包含期望事件内容，如下：

gio message is [{"cs1": "10324", "t": "cstm", "var": {"product_name": "苹果"}, "tm": 1575895053509, "n": "order"}]

code

完成以上测试步骤后：

修改gio.properties文件并将run.mode定义为production，并触发埋点事件。
在线查询GrowingIO数据库，确认数据上传成功。

Debugger选项

SDK log 输出级别

通过以下配置可以控制 sdk 的日志输出级别

# debug: 输出 debug 信息，建议连调阶段开启，可输出消息的发送报文
# error: 仅输出 错误日志，不会输出 debug 级别的信息
logger.level=debug

自定义SDK log 输出

通过以下配置，可自定义日志输出实现类, 默认为 io.growing.sdk.java.logger.GioLoggerImpl 会将日志输出到控制台

logger.implementation=io.growing.sdk.java.demo.DemoLogger

自定义日志输出实现类示例，DemoLogger 类需要客户自己实现，客户可根据自己的系统内部的日志工具将 sdk 的日志输出，并制定适合自己业务的日志保存策略

public class DemoLogger implements GioLoggerInterface {
    private final Logger logger = LoggerFactory.getLogger(DemoLogger.class);

    public void debug(String msg) {
        logger.debug(msg);
    }

    public void error(String msg) {
        logger.error(msg);
    }
}

比如以上 demo 中，采用的就是 SLF4J 和 Log4j2 的组合, 客户可通过自己的日志工具定制日志保留时间，及日志存储大小。

自定义配置文件路径

需要在 GrowingAPI 初始化之前调用 initConfig(String configFilePath)，进行配置初始化

自定义配置

如果需要自定义 Properties 进行配置初始化，则需要在 GrowingAPI 初始化之前调用 initConfig(Properties properties)，进行配置初始化。
自定义 properties key 参考 gio_default.properties 文件

支持 Java 6 版本环境

编译源码时如果出现不再支持源选项6。请使用7或更高版本，请降低当前环境jdk版本 Protobuf 从 3.6.0 版本开始不再支持 java 6，相关信息参见Drop java 6 support

使用如下依赖方式，依赖java 6的pb版本

<dependency>
    <groupId>io.growing.sdk.java</groupId>
    <artifactId>growingio-java-sdk</artifactId>
    <version>1.0.16-cdp</version>
    <exclusions>
        <exclusion>
            <groupId>com.google.protobuf</groupId>
            <artifactId>protobuf-java</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<dependency>
    <groupId>com.google.protobuf</groupId>
    <artifactId>protobuf-java</artifactId>
    <version>3.5.1</version>
</dependency>

版本记录​

简介​

集成准备​

获取SDK初始化必传参数：AccountID、DataSourceID、Host​

创建​

查看​

依赖​

配置文件信息​

事件消息​

代码示例​

API说明​

设置项目信息​

埋点事件​

登录用户属性事件​

维度表​

用户融合​

程序测试​

完成埋点事件的配置​

测试程序配置​

Debugger选项​

SDK log 输出级别​

自定义SDK log 输出​

自定义配置文件路径​

自定义配置​

支持 Java 6 版本环境​

版本记录

简介

集成准备

获取SDK初始化必传参数：AccountID、DataSourceID、Host

创建

查看

依赖

配置文件信息

事件消息

代码示例

API说明

设置项目信息

埋点事件

登录用户属性事件

维度表

用户融合

程序测试

完成埋点事件的配置

测试程序配置

Debugger选项

SDK log 输出级别

自定义SDK log 输出

自定义配置文件路径

自定义配置

支持 Java 6 版本环境