# 用户属性上报

> 来源：https://help.gravity-engine.com/docs/client-sdk/android/user-properties
> 说明如何使用 Gravity Engine Android SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。



本文档详细介绍了SDK提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。

通过本功能，您可以：

* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务

> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**

## 1. 设置用户属性 [#1-设置用户属性]

对于一般的用户属性，您可以调用 `user_set` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。

```java
// 若某key已存在则覆盖其值
JSONObject jsonObject = new JSONObject();
jsonObject.put("$name", "turboUserName");
jsonObject.put("$gender", "男");
gravityEngineSDKInstance.user_set(jsonObject);
```

## 2. 初始化用户属性 [#2-初始化用户属性]

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

```java
JSONObject jsonObject = new JSONObject();
jsonObject.put("$gender", "male");
gravityEngineSDKInstance.user_setOnce(jsonObject);
```

## 3. 累加用户属性 [#3-累加用户属性]

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

```java
// 增加或减少一个用户的某个NUMBER类型的Profile值
gravityEngineSDKInstance.user_increment("$age", 27);
```

## 4. 用户属性取最大值 [#4-用户属性取最大值]

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

```java
gravityEngineSDKInstance.user_max("ad_ecpm_max", 300);
```

## 5. 用户属性取最小值 [#5-用户属性取最小值]

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

```java
gravityEngineSDKInstance.user_min("ad_ecpm_min", 100);
```

## 6. 用户属性追加（Array） [#6-用户属性追加array]

对用户喜爱的电影、用户点评过的餐厅等属性，可以调用 `user_append` 记录列表型属性，例如：

```java
// 向某个用户的某个数组类型的用户表添加一个或者多个值,默认不去重
JSONArray moviesJsonArray = new JSONArray();
moviesJsonArray.put("Interstellar");
moviesJsonArray.put("The Negro Motorist Green Book");
JSONObject jsonObject = new JSONObject();
jsonObject.put("Movies", moviesJsonArray);
gravityEngineSDKInstance.user_append(jsonObject);
```

## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]

调用 `user_uniqAppend` 用来对 Array 类型的用户数据去重追加元素，例如：

```java
// 向某个用户的某个数组类型的用户表添加一个或者多个值，会做去重
JSONArray moviesJsonArray = new JSONArray();
moviesJsonArray.put("Interstellar");
moviesJsonArray.put("The Negro Motorist Green Book");
JSONObject jsonObject = new JSONObject();
jsonObject.put("Movies", moviesJsonArray);
gravityEngineSDKInstance.user_uniqAppend(jsonObject);
```

## 8. 清空用户属性 [#8-清空用户属性]

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

```java
// 删除一个用户的所有属性值
gravityEngineSDKInstance.user_delete();
```

## 9. 重置用户属性 [#9-重置用户属性]

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

```java
// 将某个用户的某些属性值设置为空
gravityEngineSDKInstance.user_unset("$name");
```