# 用户属性上报

> 来源：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` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    // 设置用户属性
    //此时"username"为"GravityEngineUser"
    [instance user_set:@{@"username": @"GravityEngineUser"}];
    //此时"username"为"TestUserName"
    [instance user_set:@{@"username": @"TestUserName"}];
    ```
  </Tab>

  <Tab value="Swift">
    ```swift
    // 设置用户属性
    //此时"username"为"GravityEngineUser"
    instance.user_set(["usernaame": "GravityEngineUser"])
    //此时"username"为"TestUserName"
    instance.user_set(["usernaame": "TestUserName"])
    ```
  </Tab>
</Tabs>

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

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

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="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"}];
    ```
  </Tab>

  <Tab value="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"])
    ```
  </Tab>
</Tabs>

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

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

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    //此时$age为30
    [instance user_increment:@{@"$age": @30}];

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

  <Tab value="Swift">
    ```swift
    //此时$age为30
    instance.user_increment(["$age": 30])

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

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

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

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    //此时$age为30
    [instance user_number_max:@{@"$age": @30}];

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

  <Tab value="Swift">
    ```swift
    //此时$age为30
    instance.user_number_max(["$age": 30])

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

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

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

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    //此时$age为30
    [instance user_number_min:@{@"$age": @30}];

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

  <Tab value="Swift">
    ```swift
    //此时$age为30
    instance.user_number_min(["$age": 30])

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

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

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

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    // 调用 user_append 为用户属性 Movies 追加元素。
    [instance user_append:@{@"Movies": @[@"Interstellar", @"The Negro Motorist Green Book"]}];
    ```
  </Tab>

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

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

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

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    // 调用 user_uniqAppend 为用户属性 Movies 去重追加元素。
    [instance user_uniqAppend:@{@"Movies": @[@"Interstellar", @"The Negro Motorist Green Book"]}];
    ```
  </Tab>

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

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

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

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    [instance user_delete];
    ```
  </Tab>

  <Tab value="Swift">
    ```swift
    instance.user_delete()
    ```
  </Tab>
</Tabs>

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

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

<Tabs items="['Objective-C', 'Swift']">
  <Tab value="Objective-C">
    ```objective-c
    // 清空该用户的累计付费金额属性值
    [instance user_unset:@"total_pay"];
    ```
  </Tab>

  <Tab value="Swift">
    ```swift
    // 清空该用户的累计付费金额属性值
    instance.user_unset("total_pay")
    ```
  </Tab>
</Tabs>