---
code: java_sdk_installation
name: "Java"
wikiToken: SMGDw5xMCiGynekTD0ccp9OJnQd
parentWikiToken: O3YxwgHGiiEnvYkHCcIcX51inkf
updateTime: 1767773958000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=java_sdk_installation
---
# Java

::: tip 提示

 在接入前, 请先阅读接入前准备。

Java SDK最低兼容 JDK 8 版本

 :::

**最新版本为**：v3.0.4-beta.1

**更新时间为**：2026-01-07

**资源下载**: 源代码

::: warning 注意

当前文档适用于 v3.0.0 及以后的版本，历史版本请参考 Java SDK 接入指南（V2）

SDK 的 API 是线程安全的，默认为同步调用。当上报数据量过大时，您可以在子线程中调用 API，避免影响业务线程。

::: 

### 一、集成SDK

1. 使用 Maven 集成 SDK，请在`pom.xml`文件中置入以下依赖信息:

```
<dependencies>
    // others...
    <dependency>
        <groupId>cn.thinkingdata</groupId>
        <artifactId>thinkingdatasdk</artifactId>
        <version>3.0.2</version>
    </dependency>
</dependencies>
```

2. 安装Logbus

我们推荐使用SDK+LogBus的形式，完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南

### 二、初始化

#### 方式一

```
*TDAnalytics te *= new TDAnalytics(new TDLoggerConsumer("LOG_DIRECTORY"), false);
```

`LOG_DIRECTORY`为数据写入的文件夹路径。

#### 方式二

SDK 支持传入配置进行初始化，你可以通过配置精细化控制 SDK 的功能。例如可以给日志文件添加前缀。

```
TDLoggerConsumer.Config config = new TDLoggerConsumer.Config("LOG_DIRECTORY");
config.setFilenamePrefix("unique_name");
*TDAnalytics te *= new TDAnalytics(new TDLoggerConsumer(config), false);
```

### 三、常用功能

为了保证访客 ID 与账号 ID 能够顺利进行绑定，如果您的游戏中会用到访客 ID 与账号 ID，我们极力建议您同时上传这两个 ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的 ID 绑定规则可参考用户识别规则一章。

#### 3.1 发送事件

 您可以调用`track`来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，以下是发送事件的示例代码:

```
//设置事件属性
HashMap<String,Object> properties = new HashMap<>();
// 设置用户的ip地址，TE系统会根据IP地址解析用户的地理位置信息
properties.put("#ip", "192.168.1.1");//字符串
properties.put("channel","te");//字符串
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 {
    te.track("account_id","distinct_id","payment",properties);
} catch (Exception e) {
    System.*out*.println("except:"+e);
}
```

- 事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。
- Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,TE会统一转化为小写字母
- Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组
<!-- unsupported block: 34 -->

**用户属性的要求与事件属性保持一致**

#### 3.2 设置用户属性

对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

```
//此时username为TA
Map<String,Object> userProperties = new HashMap<String,Object>();
userProperties.put("user_name", "TA");
try {
   te.userSet("account_id","distinct_id",userProperties);
} catch (Exception e) {
  System.out.println("except:"+e);
}
 
//此时userName为TE
Map<String,Object> newUserProperties = new HashMap<String,Object>();
newUserProperties.put("user_name", "TE");
try {
   te.userSet("account_id","distinct_id",newUserProperties);
} catch (Exception e) {
  System.out.println("except:"+e);
}

```

#### 3.3 数据上报

使用 TDLogConsumer 时，采集到的事件会先编码成 json 字符串，然后添加到缓存中。当缓存中的字符串长度超出设置的长度时才会将数据写入磁盘。默认最大长度为 8192 byte。

在某些业务场景下，如果您期望数据立即上报到TE服务器，可以通过调用`flush()`接口完成。需要注意，频繁调用`flush()`会导致服务性能下降。

```
te.flush();
```

#### 3.4 关闭SDK

```
try{
   te.close();
} catch (Exception e) {
    System.out.println("except:"+e);
}
```

<!-- unsupported block: 34 -->

关闭并退出 sdk，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

### 四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

```
//初始化SDK, LOG_DIRECTORY 为写入本地的文件夹地址
*TDAnalytics te *= new TDAnalytics(new TDLoggerConsumer("LOG_DIRECTORY"), false);

//设置事件属性
HashMap<String,Object> properties = new HashMap<>();
// 设置用户的ip地址，TE系统会根据IP地址解析用户的地理位置信息
properties.put("#ip", "192.168.1.1");//字符串
properties.put("channel","te");//字符串
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 {
    te.track("account_id","distinct_id","payment",properties);
} catch (Exception e) {
    System.*out*.println("except:"+e);
}

//设置用户属性
Map<String,Object> userProperties = new HashMap<String,Object>();
userProperties.put("user_name", "TE");
try {
   te.userSet("account_id","distinct_id",userProperties);
} catch (Exception e) {
  System.out.println("except:"+e);
}
```
