用户信息

需要进行控制台设置

getConsentedUserData要使用它，首先需要在控制台注册用户信息获取。请先查看用户信息介绍文档。

获取用户信息 (getConsentedUserData)

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

签名

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

类型

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应用版本为 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	迷你应用中未设置用户数据提供同意文的情况。
INVALID_REQUEST	consentedUserDataKey为空，或 termsUrl不存在，或者不是 HTTPS 公司域名的情况。
CANCELED	条款 WebView 在发送结果前被关闭的情况。
CONSENTED_USER_DATA_AGREEMENT_FAILED	处理条款 WebView 时发生错误的情况。
CONSENTED_USER_DATA_INVALID_DATA	PROVIDED但 数据没有，或者同意成功后重新查询的结果 PROVIDED不是该值的情况。

示例

WebView

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);
  }
}

React Native

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);
  }
}

注意事项

• USER_ADDRESS, USER_EMAIL在用户未在 Toss 注册的情况下 null会作为其传递。请务必处理 null。
• 如果用户要撤回同意， Toss应用 → 设置 → 条款及个人信息处理同意 → 迷你应用名称中可以按项目单独撤回。