服务端集成 · 事件采集 · Java SDK

介绍 Gravity Engine 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.9</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 比较数值大小，保存较大的值。

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

用户属性取最小值

对于数值型的用户属性，可以使用 userMin 比较数值大小，保存较小的值。

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() 方法

Java SDK

本页内容