# 用户属性上报

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





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

通过本功能，您可以：

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

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

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

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

**Objective-C**

```objective-c
// 设置用户属性
//此时"username"为"GravityEngineUser"
[instance user_set:@{@"username": @"GravityEngineUser"}];
//此时"username"为"TestUserName"
[instance user_set:@{@"username": @"TestUserName"}];
```

**Swift**

```swift
// 设置用户属性
//此时"username"为"GravityEngineUser"
instance.user_set(["usernaame": "GravityEngineUser"])
//此时"username"为"TestUserName"
instance.user_set(["usernaame": "TestUserName"])
```

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

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

**Objective-C**

```objective-c
//first_payment_time为2023-01-01 04:43:35.968
[instance user_set_once:@{@"first_payment_time": @"2023-01-01 04:43:35.968"}];
//first_payment_time仍然为2023-01-01 04:43:35.968
[instance user_set_once:@{@"first_payment_time": @"2018-12-31 01:23:45.678"}];
```

**Swift**

```swift
//first_payment_time为2023-01-01 04:43:35.968
instance.user_set_once(["first_payment_time": "2023-01-01 04:43:35.968"])
//first_payment_time仍然为2023-01-01 04:43:35.968
instance.user_set_once(["first_payment_time": "2018-12-31 01:23:45.678"])
```

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

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

**Objective-C**

```objective-c
//此时$age为30
[instance user_increment:@{@"$age": @30}];

//此时$age为32
[instance user_increment:@{@"$age": @2}];
```

**Swift**

```swift
//此时$age为30
instance.user_increment(["$age": 30])

//此时$age为32
instance.user_increment(["$age": 2])
```

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

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

**Objective-C**

```objective-c
//此时$age为30
[instance user_number_max:@{@"$age": @30}];

//此时$age仍为30
[instance user_number_max:@{@"$age": @27}];
```

**Swift**

```swift
//此时$age为30
instance.user_number_max(["$age": 30])

//此时$age仍为30
instance.user_number_max(["$age": 27])
```

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

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

**Objective-C**

```objective-c
//此时$age为30
[instance user_number_min:@{@"$age": @30}];

//此时$age仍为30
[instance user_number_min:@{@"$age": @100}];
```

**Swift**

```swift
//此时$age为30
instance.user_number_min(["$age": 30])

//此时$age仍为30
instance.user_number_min(["$age": 100])
```

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

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

**Objective-C**

```objective-c
// 调用 user_append 为用户属性 Movies 追加元素。
[instance user_append:@{@"Movies": @[@"Interstellar", @"The Negro Motorist Green Book"]}];
```

**Swift**

```swift
// 调用 user_append 为用户属性 Movies 追加元素。
instance.user_append(["Movies": ["Interstellar", "The Negro Motorist Green Book"]]);
```

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

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

**Objective-C**

```objective-c
// 调用 user_uniqAppend 为用户属性 Movies 去重追加元素。
[instance user_uniqAppend:@{@"Movies": @[@"Interstellar", @"The Negro Motorist Green Book"]}];
```

**Swift**

```swift
// 调用 user_uniqAppend 为用户属性 Movies 去重追加元素。
instance.user_uniqAppend(["Movies": ["Interstellar", "The Negro Motorist Green Book"]]);
```

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

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

**Objective-C**

```objective-c
[instance user_delete];
```

**Swift**

```swift
instance.user_delete()
```

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

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

**Objective-C**

```objective-c
// 清空该用户的累计付费金额属性值
[instance user_unset:@"total_pay"];
```

**Swift**

```swift
// 清空该用户的累计付费金额属性值
instance.user_unset("total_pay")
```