# 用户属性上报

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



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

通过本功能，您可以：

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

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

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

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

```javascript
// 设置用户属性，会员等级
ge.userSet({ vip_level: "钻石会员" });
```

> 属性格式要求与事件属性保持一致。

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

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

```javascript
// 以设置用户名为例，如果用户名已设置，则忽略本次设置
ge.userSetOnce({ user_name: "TestUser" });
```

> 属性格式要求与事件属性保持一致。

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

当您要上传数值型的属性时，您可以调用 `userAdd` 来对该属性进行累加操作。

```javascript
// 以付费为例，用户每次付费时调用此接口，则 'total_revenue' 字段每次会做累加付费金额的处理
ge.userAdd({ total_revenue: 50 });
```

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

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

当您要清空用户的某个用户属性值时，您可以调用 `userUnset` 来对指定属性进行清空操作。

```javascript
// 清空属性名为 userPropertyKey 的用户属性值，即设置为 NULL
ge.userUnset("userPropertyKey");
```

> `userUnset` 的传入值为被清空属性的 Key 值。

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

如果您要删除某个用户，可以调用 `userDel` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

```javascript
ge.userDel();
```

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

您可以调用 `userAppend` 对 Array（List）类型的用户数据追加元素。

```javascript
ge.userAppend({ Movies: ["Interstellar", "The Negro Motorist Green Book"] });
```

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

`userUniqAppend` 用来对 Array（List）类型的用户数据**去重**追加元素。

```javascript
ge.userUniqAppend({
  Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```

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

`userNumberMax` 用来比较数值大小，保存较大的。

```javascript
ge.userNumberMax({
  ad_ecpm_max: 300,
});
```

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

`userNumberMin` 用来比较数值大小，保存较小的。

```javascript
ge.userNumberMin({
  ad_ecpm_min: 17,
});
```