User.getConsentedData

함수형 API getConsentedUserData로도 같은 기능을 쓸 수 있어요.

기능 설명

사용자 동의 기반 데이터를 요청해요. 동의가 필요하면 약관 웹뷰를 띄우고, 동의가 완료되면 서버에서 조회한 데이터를 반환해요.

토스앱 5.264.0 이상에서 사용할 수 있어요. 호출 전에 User.getConsentedData.isSupported()로 지원 여부를 확인할 수 있어요. 함수형 API getConsentedUserData는 미지원 버전에서 undefined를 반환하고, User.getConsentedData는 UNSUPPORTED_APP_VERSION 에러를 던져요.

타입

User.getConsentedData(options: GetConsentedUserDataOptions): Promise<ConsentedUserData>;

Params

interface GetConsentedUserDataOptions {
  /** 서버가 사용자 데이터 제공 동의문과 데이터 묶음을 찾을 때 쓰는 key예요. 예: `cud_delivery` */
  consentedUserDataKey: string;
  /** `USER_DECLINED` 상태에서도 다시 약관 웹뷰를 띄울지 여부예요. 기본값은 `false`예요. */
  shouldRequestAgreementWhenUserDeclined?: boolean;
}

Response

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

요청한 항목에 해당하는 키만 포함될 수 있어요.

에러

에러 코드는 catch한 에러의 error.code 값이에요.

코드	설명
UNSUPPORTED_APP_VERSION	실행 중인 토스앱 버전이 이 기능을 지원하지 않으면 호출 즉시 발생해요. User.getConsentedData.isSupported()로 사전 확인하고, 발생 시 error.message(업데이트 안내 문구)를 사용자에게 보여주세요.
USER_DECLINED	사용자가 명시적으로 거부했고 재요청 옵션이 없거나, 약관 웹뷰에서 동의를 거부한 경우예요.
UNAVAILABLE	서버가 사용자 동의 여부를 판단할 수 없는 경우예요.
TERMS_NOT_SET	미니앱에 사용자 데이터 제공 동의문이 설정되지 않은 경우예요.
INVALID_REQUEST	consentedUserDataKey가 비어 있거나, termsUrl이 없거나, HTTPS 회사 도메인이 아닌 경우예요.
CANCELED	약관 웹뷰가 결과를 보내기 전에 닫힌 경우예요.
CONSENTED_USER_DATA_AGREEMENT_FAILED	약관 웹뷰 처리 중 오류가 발생한 경우예요.
CONSENTED_USER_DATA_INVALID_DATA	PROVIDED인데 data가 없거나, 동의 성공 후 재조회 결과가 PROVIDED가 아닌 경우예요.

예시 코드

import { User } from "@apps-in-toss/web-framework";

async function fetchDeliveryUserData() {
  try {
    const data = await User.getConsentedData({
      consentedUserDataKey: "cud_delivery",
    });

    console.log("사용자 이름:", data?.USER_NAME);
    console.log("전화번호:", data?.USER_PHONE);
  } catch (error) {
    console.error("동의 데이터 조회 실패:", error);
  }
}