> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/user-info.md).

# 用户信息

{% hint style="info" %}
**需要进行控制台设置**

`getConsentedUserData`要使用它，首先需要在控制台注册用户信息拉取。请先查看用户信息介绍文档。
{% endhint %}

### 用户信息获取（`getConsentedUserData`)

`getConsentedUserData`是请求基于用户同意数据的函数。如果需要同意，会弹出条款 WebView，同意完成后返回从服务器查询到的数据。

**签名**

```typescript
function getConsentedUserData(options: GetConsentedUserDataOptions): Promise<ConsentedUserData | undefined>;
```

**类型**

```typescript
type GetConsentedUserDataErrorCode =
  | 'USER_DECLINED'
  | 'UNAVAILABLE'
  | 'TERMS_NOT_SET'
  | 'INVALID_REQUEST'
  | 'CANCELED'
  | 'CONSENTED_USER_DATA_AGREEMENT_FAILED'
  | 'CONSENTED_USER_DATA_INVALID_DATA';

interface GetConsentedUserDataOptions {
  consentedUserDataKey: string;
  shouldRequestAgreementWhenUserDeclined?: boolean;
}

type ConsentedUserDataKey =
  | 'USER_NAME'
  | 'USER_GENDER'
  | 'USER_NATIONALITY'
  | 'USER_BIRTHDAY'
  | 'USER_PHONE'
  | 'USER_ADDRESS'
  | 'USER_EMAIL'
  | 'USER_CONSUMPTION_HISTORY';

type ConsentedUserData = Partial<Record<ConsentedUserDataKey, string>>;
```

**参数**

* **options** · 必需 · `GetConsentedUserDataOptions`

  这是请求基于用户同意的数据时使用的选项。

  * **options.consentedUserDataKey** · 必需 · `string`

    这是服务器查找用户数据提供同意文和数据集合时使用的 key。例如： `cud_delivery`
  * **options.shouldRequestAgreementWhenUserDeclined** · `boolean`

    `USER_DECLINED` 是否在该状态下再次弹出条款 WebView。默认值为 `false`。

**返回值**

* `Promise<ConsentedUserData | undefined>`

  返回服务器提供的用户数据。Toss App 版本为 `5.264.0` 低于 `undefined`会返回。

`ConsentedUserData`中可能只包含所请求项目对应的 key。

| 键                  | 说明         | 备注                                      |
| ------------------ | ---------- | --------------------------------------- |
| `USER_NAME`        | 用户名        |                                         |
| `USER_GENDER`      | 用户性别       |                                         |
| `USER_NATIONALITY` | 是否为本国人/外国人 |                                         |
| `USER_BIRTHDAY`    | 用户出生日期     |                                         |
| `USER_PHONE`       | 用户手机号码     |                                         |
| `USER_ADDRESS`     | 用户家庭住址     | 由于在注册 Toss 时不是必填项，可能没有值；这种情况下会传递为 null。 |
| `USER_EMAIL`       | 用户电子邮箱地址   | 由于在注册 Toss 时不是必填项，可能没有值；这种情况下会传递为 null。 |

**错误代码**

`getConsentedUserData` 如果调用失败，可能会返回以下错误码。

| 错误代码                                   | 说明                                                            |
| -------------------------------------- | ------------------------------------------------------------- |
| `USER_DECLINED`                        | 用户明确拒绝，且没有重新请求选项，或者在条款 WebView 中拒绝同意的情况。                      |
| `UNAVAILABLE`                          | 服务器无法判断用户是否同意的情况。                                             |
| `TERMS_NOT_SET`                        | Mini App 中未设置用户数据提供同意文的情况。                                    |
| `INVALID_REQUEST`                      | `consentedUserDataKey`为空，或者 `termsUrl`不存在，或者不是 HTTPS 公司域名的情况。 |
| `CANCELED`                             | 条款 WebView 在发送结果之前被关闭的情况。                                     |
| `CONSENTED_USER_DATA_AGREEMENT_FAILED` | 处理条款 WebView 时发生错误的情况。                                        |
| `CONSENTED_USER_DATA_INVALID_DATA`     | `PROVIDED`但 `data`不存在，或者同意成功后重新查询结果 `PROVIDED`不是该值的情况。        |

**示例**

{% tabs %}
{% tab title="WebView" %}

```tsx
import { getConsentedUserData } from '@apps-in-toss/web-framework';

async function fetchDeliveryUserData() {
  try {
    const data = await getConsentedUserData({
      consentedUserDataKey: 'cud_delivery',
    });

    console.log('用户名：', data?.USER_NAME);
    console.log('电话号码：', data?.USER_PHONE);
  } catch (error) {
    console.error('同意数据查询失败：', error);
  }
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { getConsentedUserData } from '@apps-in-toss/framework';

async function fetchDeliveryUserData() {
  try {
    const data = await getConsentedUserData({
      consentedUserDataKey: 'cud_delivery',
    });

    console.log('用户名：', data?.USER_NAME);
    console.log('电话号码：', data?.USER_PHONE);
  } catch (error) {
    console.error('同意数据查询失败：', error);
  }
}
```

{% endtab %}
{% endtabs %}

### 注意事项

* `USER_ADDRESS`, `USER_EMAIL`如果用户未在 Toss 中注册 `null`则会传递为该值。请务必处理 null。
* 如果用户要撤回同意 **Toss App → 设置 → 条款及个人信息处理同意 → Mini App 名称**中可按项目单独撤回。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/user-info.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.