菜单

Java SDK

概述

Gravity Engine Java SDK 是一个用于数据采集和上报的工具，帮助开发者轻松集成事件追踪和用户行为分析功能。本 SDK 兼容 JDK 8 及以上版本。在接入前, 请先阅读接入前准备。

服务端接入Java SDK，完成事件的服务端报送功能，您需要注意以下几点：

服务端SDK仅负责事件的收集上报，不负责用户的注册，用户注册需要调用客户端 SDK 的 initialize 方法完成；
客户端和服务端SDK使用的用户 client id 需要保持一致；
在客户端完成 initialize 方法调用之后，服务端SDK才能开始做事件采集上报，否则上报不成功；
服务端SDK接入事件上报时，请参考元事件页面下关于事件的详情属性；
请尽量上报事件的公共属性，引力不做强制要求，但是上报足够多属性，可以方便您后续在引力平台使用数据分析功能（ $city、 $province 、 $country 、 $browser 、 $browser_version 属性可以不上报，引力后端会自动采集）；
关于属性的更多信息，请您参考事件属性页面。

1. 环境要求

JDK 8 或更高版本
Maven 项目管理工具

2. 安装集成

Maven 集成

Maven配置私有仓库：https://nexus.gravity-engine.com/repository/maven-releases/

<settings
    xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>nexus-profile</id>
            <repositories>
                <repository>
                    <id>maven-nexus</id>
                    <url>https://nexus.gravity-engine.com/repository/maven-releases/</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                </repository>
            </repositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>nexus-profile</activeProfile>
    </activeProfiles>
</settings>

在项目的 pom.xml文件中添加以下依赖：

<dependencies>
    <dependency>
        <groupId>cn.gravity.java</groupId>
        <artifactId>gedata</artifactId>
        <version>3.0.8</version>
    </dependency>
</dependencies>

手动下载

也可以直接下载 JAR 文件：下载地址

3. 初始化配置

基础配置

public final static String GE_SERVER_MAIN_URL = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/";
public final static String GE_ACCESS_TOKEN = "你的ACCESS_TOKEN";

public static String getMainServerUri() {
    return GE_SERVER_MAIN_URL + "?access_token=" + GE_ACCESS_TOKEN;
}

选择数据上报模式

批量上报模式（推荐）

public static IGEConsumer generateBatchConsumer() {
    IGEConsumer consumer = null;
    try {
        GEBatchConsumer.Config config = new GEBatchConsumer.Config();
        config.setBatchSize(20);      // 批量大小
        config.setMaxCacheSize(10);   // 最大缓存数量
        String url = getMainServerUri();
        consumer = new GEBatchConsumer(url, config);
    } catch (Exception ignored) {
    }
    return consumer;
}

// 初始化
IGEConsumer consumer = generateBatchConsumer();
GEAnalytics ge = new GEAnalytics(consumer, false);

核心功能

1. 事件追踪

如需上报自定义事件，您必须先在元事件中添加，否则会上报失败！

您可以调用 track 方法，记录用户自定义事件。

您需要先在元事件中添加自定义事件，然后调用 track 方法上报自定义事件。

// 设置事件属性
HashMap<String,Object> properties = new HashMap<>();

// 支持的数据类型
properties.put("#ip", "192.168.1.1");           // 字符串
properties.put("channel", "ge");                // 字符串
properties.put("age", 1);                       // 数字
properties.put("isSuccess", true);              // 布尔值
properties.put("birthday", new Date());         // 时间

// 对象类型
HashMap<String,Object> object = new HashMap<>();
object.put("key", "value");
properties.put("object", object);

// 对象数组
HashMap<String,Object> object1 = new HashMap<>();
object1.put("key", "value");
ArrayList<Object> arr = new ArrayList<>();
arr.add(object1);
properties.put("object_arr", arr);

// 普通数组
ArrayList<String> arr1 = new ArrayList<>();
arr1.add("value");
properties.put("arr", arr1);

// 发送事件
try {
    ge.track("client_id", "payment", properties);
} catch (Exception e) {
    System.out.println("异常:" + e);
}

事件名称是 String 类型，只能以字母开头，可包含数字，字母和下划线 “_”，长度最大为 50 个字符。
事件属性是 Map<String, Object> 类型，其中每个元素代表一个属性；
- 事件属性 Key 为属性名称，为 String 类型，规定只能以字母开头，包含数字，字母和下划线 “_”，长度最大为 50 个字符；
- 属性 Value 支持String、int、float、boolean、Date、List<String>；当事件属性为列表类型时，您需要使用 JSONArray 传入，不要使用 ArrayList，否则会校验失败！

2. 用户属性管理

设置用户属性（覆盖）

对于一般的用户属性，您可以调用userSet来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性。

Map<String,Object> userProperties = new HashMap<>();
userProperties.put("user_name", "GE");
try {
    ge.userSet("client_id", userProperties);
} catch (Exception e) {
    System.out.println("异常:" + e);
}

初始化用户属性（仅首次设置有效）

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

ge.userSetOnce("client_id", new HashMap<String, Object>() {{
    put("first_login_time", "2023-01-01");
}});

累加用户属性

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

ge.userIncrement("client_id", new HashMap<String, Object>() {{
    put("login_count", 1);
}});

用户属性取最大值

对于数值型的用户属性，可以使用 userMax用来比较数值大小，保存较大的，如果没有这个 key，则新增 key，value 取本次的值。

ge.userMax("client_id", new HashMap<String, Object>() {{
    put("max_score", 200);
}});

用户属性取最小值

对于数值型的用户属性，可以使用 useMin 用来比较数值大小，保存较小的，如果没有这个 key，则新增 key，value 取本次的值。

ge.userMin("client_id", new HashMap<String, Object>() {{
    put("min_score", 100);
}});

用户属性追加

对用户喜爱的电影、用户点评过的餐厅等属性，可以调用 userAppend 记录列表型属性。

ge.userAppend("client_id", new HashMap<String, Object>() {{
    ArrayList<String> tags = new ArrayList<>();
    tags.add("VIP");
    tags.add("Active");
    put("user_tags", tags);
}});

用户属性去重追加

调用 userUniqAppend 用来对 Array 类型的用户数据去重追加元素。

ge.userUniqAppend("client_id", new HashMap<String, Object>() {{
    ArrayList<String> tags = new ArrayList<>();
    tags.add("VIP");
    tags.add("Active");
    put("user_tags", tags);
}});

重置用户属性

如果需要重置已设置的某个用户属性，可以调用 userUnset 进行重置。

ge.userUnset("client_id", "unwanted_property");

清空用户属性

调用 userDelete 方法，将把当前用户属性清空，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

ge.userDelete("client_id");

3. 数据管理

立即上报数据

ge.flush();

注意: 频繁调用 flush() 会影响性能，建议在重要操作后调用。

关闭 SDK

ge.close();

在应用关闭前调用，确保缓存数据不会丢失。

完整示例

import cn.gravity.java.sdk.GEAnalytics;
import cn.gravity.java.sdk.GEBatchConsumer;
import cn.gravity.java.sdk.inter.IGEConsumer;

import java.util.HashMap;
import java.util.Map;

public class GravityEngineExample {
    private static final String ACCESS_TOKEN = "你的ACCESS_TOKEN";
    private static GEAnalytics ge;
    
    public static void main(String[] args) {
        // 初始化
        initializeSDK();
        
        // 设置用户属性
        setUserProperties();
        
        // 发送事件
        trackEvents();
        
        // 清理资源
        cleanup();
    }
    
    private static void initializeSDK() {
        String url = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=" + ACCESS_TOKEN;
        
        GEBatchConsumer.Config config = new GEBatchConsumer.Config();
        config.setBatchSize(20);
        config.setMaxCacheSize(10);
        
        IGEConsumer consumer = new GEBatchConsumer(url, config);
        ge = new GEAnalytics(consumer, false);
        
        // 开启日志
        GEAnalytics.enableLog(true);
    }
    
    private static void setUserProperties() {
        String clientId = "user_123";
        
        // 设置基础属性
        Map<String, Object> properties = new HashMap<>();
        properties.put("user_name", "张三");
        properties.put("city", "北京");
        properties.put("age", 28);
        
        ge.userSet(clientId, properties);
        
        // 首次设置注册时间
        ge.userSetOnce(clientId, new HashMap<String, Object>() {{
            put("register_time", "2023-01-01");
        }});
        
        // 增加登录次数
        ge.userIncrement(clientId, new HashMap<String, Object>() {{
            put("login_count", 1);
        }});
    }
    
    private static void trackEvents() {
        String clientId = "user_123";
        
        Map<String, Object> properties = new HashMap<>();
        properties.put("#ip", "192.168.1.1");
        properties.put("product_id", "P001");
        properties.put("amount", 199.9);
        properties.put("currency", "CNY");
        
        try {
            ge.track(clientId, "purchase", properties);
        } catch (Exception e) {
            System.out.println("事件发送失败: " + e.getMessage());
        }
    }
    
    private static void cleanup() {
        // 确保数据上报
        ge.flush();
        
        // 关闭SDK
        ge.close();
    }
}

最佳实践

批量上报: 生产环境推荐使用批量上报模式，平衡性能和实时性
异常处理: 对所有SDK调用进行异常捕获
资源清理: 在应用关闭前调用 close()方法
属性命名: 使用有意义的属性名称，保持一致性
数据类型: 确保属性值类型符合预期，避免类型错误

故障排除

常见问题

初始化问题: 检查 ACCESS_TOKEN 和服务器地址是否正确
数据格式: 验证事件属性数据类型是否符合要求
性能问题: 避免频繁调用 flush() 方法

上一个

Restful API

下一个

Python SDK

最近修改: 2026-01-12Powered by