---
code: java_sdk_advanced
name: "进阶指南"
wikiToken: YWaKwdZQ1irX0gkvF5pcq6HanBg
parentWikiToken: SMGDw5xMCiGynekTD0ccp9OJnQd
updateTime: 1745309852000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=java_sdk_advanced
---
# 进阶指南

### 一、发送事件

在 SDK 初始化完成之后，您就可以进行数据埋点，收集用户的行为信息。一般情况下普通事件即可满足业务场景需求，您也可以根据自己的实际业务场景使用首次、可更新等事件。

#### 1.1 普通事件

您可以调用 `track` 来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送事件的条件，此处以用户购买某商品作为范例：

```
//设置事件属性
Map<String,Object> properties = new HashMap<String,Object>();
properties.put("product_name","商品名");//字符串
try {
     te.track("account_id","distinct_id","product_buy",properties);
} catch (Exception e) {
     System.out.println("except:"+e);
}
```

#### 1.2 首次事件

首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上的激活事件，则可以用首次事件来上报数据。使用”首次事件校验“特性，必须要在properties中设置#first_check_id字段，类型为字符串。

```
// 上报首次事件,事件名为 device_activation,first_check_id的值为device_id
Map<String, Object> properties = new HashMap<>();
properties.put("price",100);
properties.put("status",3);
properties.put("#first_check_id","device_id");
te.trackFirst("account_id", "distinct_id", "device_activation", properties);
```

<!-- unsupported block: 34 -->

注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 1 小时入库。

#### 1.3 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。

```
// 上报可更新事件，事件名为 UPDATABLE_EVENT
// 上报后事件属性 status 为 3, price 为 100
Map<String, Object> properties = new HashMap<>();
properties.put("price",100);
properties.put("status",3);
te.trackUpdate("account_id","distinct_id","UPDATABLE_EVENT","test_event_id",properties);

// 上报后同样的事件属性 status 被更新为 5, price 不变
Map<String, Object> protertiesNew = new HashMap<>();
protertiesNew.put("status",5);
te.trackUpdate("account_id", "distinct_id", "UPDATABLE_EVENT", "test_event_id", protertiesNew);
```

#### 1.4 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。

```
// 上报可重写事件，事件名为 OVERWRITE_EVENT
// 上报后事件属性 status 为 3, price 为 100
Map<String, Object> properties = new HashMap<>();
properties.put("price",100);
properties.put("status",3);
te.trackOverwrite("account_id","distinct_id", "OVERWRITE_EVENT","test_event_id", properties);

// 上报后事件属性 status 被更新为 5, price 属性被删除
Map<String, Object> protertiesNew = new HashMap<>();
protertiesNew.put("status",5);
te.trackOverwrite("account_id", "distinct_id", "OVERWRITE_EVENT", "test_event_id", protertiesNew);
```

### 二、用户属性

AE 平台支持的用户属性设置API有: `userSet`、`userSetOnce`、`userAdd`、`userUnset`、`userDelete`、`userAppend`、`userUniqAppend`。

#### 2.1 userSet

对于一般的用户属性，您可以调用`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);
 }
```

#### 2.2 userSetOnce

如果您要上传的用户属性只要设置一次，则可以调用`userSetOnce`来进行设置，当该属性之前已经有值的时候，将会忽略这条信息，再以设置用户名为例：

```
//first_payment_time为2018-01-01 01:23:45.678
Map<String,Object> userProperties = new HashMap<String,Object>();
userProperties.put("first_payment_time","2018-01-01 01:23:45.678");
try {
     te.userSetOnce("account_id","distinct_id",userProperties);
} catch (Exception e) {
     System.out.println("except:"+e);
 }
 
//first_payment_time仍然为2018-01-01 01:23:45.678
Map<String,Object> newUserProperties = new HashMap<String,Object>();
newUserProperties.put("first_payment_time","2018-12-31 01:23:45.678");
try {
     te.userSetOnce("account_id","distinct_id",newUserProperties);
} catch (Exception e) {
     System.out.println("except:"+e);
}
```

#### 2.3 userAdd

当您要上传数值型的属性时，您可以调用`userAdd`来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值，等同于相减操作。此处以累计付费金额为例：

```
Map<String,Object> userProperties = new HashMap<String,Object>();
userProperties.put("total_revenue",30);
//上传用户属性，此时"total_revenue"的值为30
try {
     te.userAdd("account_id","distinct_id",userProperties);
} catch (Exception e) {
     System.out.println("except:"+e);
 }

//再次上传用户属性，此时"total_revenue"的值会累加为678
Map<String,Object> newUserProperties = new HashMap<String,Object>();
newUserProperties.put("total_revenue",648);
try {
    te.userAdd("account_id","distinct_id",newUserProperties);
} catch (Exception e) {
    System.out.println("except:"+e);
}
```

<!-- unsupported block: 34 -->

设置的属性key为字符串，Value 只允许为数值。

#### 2.4 userAppend

您可以调用`userAppend`对数组类型的用户属性进行追加操作。

```
Map<String,Object> properties = new HashMap<String,Object>();
List<String> list = new ArrayList<>();
list.add("apple");
list.add("ball");
properties.put("user_list",list);
 try{
    //此时user_list的属性值为["apple"，"ball"]
    te.userAppend("account_id", "distinct_id", properties);
 } catch (Exception e) {
    System.out.println("except:"+e);
 }
```

#### 2.5 userUniqAppend

 您可以调用`userUniqAppend`对 数组类型的用户属性进行追加操作。调用`userUniqAppend`接口会对追加的用户属性进行去重，`userAppend`接口不做去重，用户属性可存在重复。

```
Map<String,Object> properties = new HashMap<String,Object>();
List<String> list = new ArrayList<>();
list.add("apple");
list.add("ball");
properties.put("user_list",list);
 
Map<String,Object> newProperties = new HashMap<String,Object>();
List<String> newList = new ArrayList<>();
newList.add("apple");
newList.add("cube");
newProperties.put("user_list", newList);
try{
   //此时user_list的属性值为["apple"，"ball"]
   te.userAppend("account_id", "distinct_id", properties);
   //此时user_list的属性值为["apple","apple","ball","cube"]
   te.userAppend("account_id", "distinct_id",newProperties);
   //此时user_list的属性值为["apple"，"ball","cube"]
   te.userUniqAppend("account_id", "distinct_id",newProperties);
} catch (Exception e) {
    System.out.println("except:"+e);
}
```

#### 2.6 userUnset

当您要清空用户的用户属性值时，您可以调用`userUnset`来对指定属性进行清空操作，如果该属性还未在集群中被创建，则`userUnset`不会创建该属性

```
// 重置多个用户属性
try {
    te.userUnset("account_id", "distinct_id", "key1", "key2", "key3");
} catch (Exception e) {
    System.out.println("except:"+e);
}
```

<!-- unsupported block: 34 -->

user_unset: 的传入值为被清空属性的 Key 值。

#### 2.7 userDelete

如果您要删除某个用户，可以调用`userDelete`将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到，该操作可能产生不可逆的后果，请慎用

```
try{
   te.userDelete("account_id","distinct_id");
} catch (Exception e) {
   System.out.println("except:"+e);
}
```

### 三、其他功能

#### 3.1 TDBatchConsumer

::: warning 注意

当数据量过大或者网络异常时，有数据丢失的风险，不建议在正式环境中使用

:::

 批量实时地向 AE 服务器传输数据，不需要搭配传输工具，因网络问题发送失败时会重试3次，仍然失败将会把数据存入缓存区，可设置缓存区大小，默认50，即缓存区保留的数据总数最大为50*20（20为每次上传的batch值，可设置）。

```
TDAnalytics te = null;
try {
    te = new TDAnalytics(new TDBatchConsumer("SERVER_URL", "APPID"));
} catch (Exception ignored){

}
```

参数说明:

- `APPID`: 您的项目的 APPID，可通过在 AE 后台项目管理页面获取
- `SERVER_URL`: 数据上传的 URL
- 如果您对接的是云服务，填入: https://global-receiver-ta.thinkingdata.cn 
- 如果您使用私有化部署版本，请为数据采集地址绑定域名，并配置 HTTPS 证书：https://数据采集地址绑定域名
#### 3.2 定时刷新功能

可以配置 Config 中的 interval 和 autoFlush 参数开启定时上报数据的功能。

```
TDAnalytics te = null;

// e.g. TDLogConsumer
try {
    TDLoggerConsumer.Config config = new TDLoggerConsumer.Config("./log");
    // The cache event is reported every 10 seconds
    config.setAutoFlush(true);
    config.setInterval(10);
    te = new TDAnalytics(new TDLoggerConsumer(config));
} catch (Exception ignored){}

// e.g. TDBatchConsumer
try {
    TDBatchConsumer.Config config = new TDBatchConsumer.Config();
    // The cache event is reported every 10 seconds
    config.setAutoFlush(true);
    config.setInterval(10);
    te = new TDAnalytics(new TDBatchConsumer("url", "appId", config));
} catch (Exception ignored){}
```
