사용자 프로필 수집
사용자 로그인에 필요한 인증 (Authentication) 식별자 및 자격 증명 외에도, 애플리케이션에서 개인화된 제품 경험을 제공하기 위해 Logto에 저장된 추가 사용자 프로필 정보를 수집해야 할 수 있습니다. 이 정보는 JWT 클레임 또는 API를 통해 쉽게 조회할 수 있습니다. 사용자 데이터를 수집하는 방법은 다음과 같습니다:
-
신규 사용자 등록 시: 사용자 프로필 수집 기능을 사용하여, 회원가입 과정에서 추가 사용자 프로필 정보를 수집하는 "자기소개" 단계를 기본 제공으로 추가할 수 있습니다. 신규 사용자는 모든 필수 항목을 완료해야 등록이 완료됩니다. 이 문서는 이 방법에 중점을 둡니다.
-
사용자 등록 후: 기본 제공 Account Center 프로필 페이지 또는 Account API를 사용하여 사용자가 자신의 프로필 정보를 조회 및 수정할 수 있도록 할 수 있습니다. Account Center는 여기서 정의한 동일한 프로필 필드를 표시하도록 구성할 수 있으므로, 사용자는 회원가입 후에도 프로필 데이터를 계속 편집할 수 있습니다.
주요 이점
사용자 프로필 수집 기능을 통해 최종 사용자 등록 과정에서 추가 사용자 정보를 수집할 수 있습니다. 제품에 꼭 필요한 정보만 수집하여, 사용자 전환율에 영향을 줄 수 있는 긴 회원가입 과정을 피하는 것을 권장합니다.
이 기능을 통해 다음을 할 수 있습니다:
-
포괄적인 사용자 데이터 수집: 사용자 데이터 및 OIDC 표준 사용자 속성, 맞춤 데이터 등 비즈니스 또는 컴플라이언스 목적의 모든 정보를 수집할 수 있습니다.
-
유연한 필드 커스터마이즈: 텍스트, 숫자, 날짜, 체크박스, 드롭다운(선택), URL, 정규식 검증 등 다양한 필드 유형 중에서 선택하여 데이터 요구사항에 맞게 설정할 수 있습니다.
-
최적화된 사용자 경험: 라벨, 설명, 플레이스홀더, 검증 규칙 등 표시를 커스터마이즈할 수 있습니다. 비즈니스 요구에 따라 필드를 필수 또는 선택으로 설정할 수 있습니다.
-
내장 필드 구성: 일반 사용자 속성을 위한 사전 구성된 기본 데이터 필드를 플러그 앤 플레이 방식으로 사용할 수 있습니다. 복합 필드(주소, 전체 이름)를 활용해 한 번에 구조화된 데이터를 효율적으로 수집할 수 있습니다.
빠른 시작
-
Logto 콘솔 > 로그인 & 계정 > 사용자 프로필 수집
로 이동하세요. - "프로필 필드 추가"를 클릭하고, 기본 제공 필드를 선택하거나 맞춤 데이터 (영숫자 키)를 정의하여 생성하세요.
- 필드 상세 설정에서 필드 유형, 라벨, 설명, 필수 여부, 유형별 설정(길이, 범위, 형식, 옵션 등)을 지정한 후 "변경 사항 저장"을 클릭하세요.
- 로그인 & 계정 > 사용자 프로필 수집 화면으로 돌아가, 필드를 드래그 앤 드롭하여 순서를 변경하면 변경 사항이 자동으로 적용됩니다.
- Logto 라이브 프리뷰 또는 테스트 앱에서 사용자 경험을 테스트하세요. 사용자가 식별자(이메일/휴대폰 번호/사용자명), 소셜 로그인, 엔터프라이즈 SSO로 새 계정을 생성하더라도, 회원가입 과정에서 모두 "자기소개" 페이지를 보게 됩니다.
사용자 데이터 유형
사용자 데이터는 각 사용자 프로필에서 확인할 수 있습니다. 모든 사용자 데이터 카테고리에 대한 종합적인 개요는 사용자 데이터 구조 문서를 참고하세요. 사용자 프로필 수집 기능을 통해 회원가입 시 기본 사용자 데이터와 맞춤 사용자 데이터를 모두 수집할 수 있습니다.
기본 사용자 데이터 필드
Logto에서 제공하는 기본 사용자 데이터 필드는 user 또는 user.profile 속성에 직접 저장됩니다. 이 필드들은 기본 구성 값과 i18n 번역이 적용되어, 생성 즉시 바로 사용할 수 있습니다. 또한, 필요에 따라 필드 유형과 파라미터를 커스터마이즈할 수 있습니다.
| 필드명 | 사용자 데이터 키 | 설명 |
|---|---|---|
| 이름 | user.name | 모든 이름 구성 요소를 포함한 사용자의 전체 표시 이름 (예: "Jane Doe"). |
| 전체 이름 | user.profile.givenNameuser.profile.middleNameuser.profile.familyName | 사용자의 공식 전체 이름. familyName, givenName, middleName을 설정에 따라 유연하게 조합합니다. |
| 닉네임 | user.profile.nickname | 사용자의 비공식 또는 친근한 이름으로, 공식 이름과 다를 수 있습니다. |
| 생년월일 | user.profile.birthdate | 지정된 형식(예: "MM-dd-yyyy")의 사용자의 생년월일. |
| 성별 | user.profile.gender | 사용자가 스스로 식별하는 성별 (예: "여성", "남성", "응답하지 않음" 등). |
| 프로필 | user.profile.profile | 사용자의 사람이 읽을 수 있는 프로필 페이지의 URL (예: 소셜 미디어 프로필). |
| 웹사이트 | user.profile.website | 사용자의 개인 웹사이트 또는 블로그의 URL. |
| 주소 | user.profile.address.formatteduser.profile.address.streetAddressuser.profile.address.regionuser.profile.address.zoneinfouser.profile.address.postalCodeuser.profile.address.country | 사용자의 전체 주소 (예: "123 Main St, Anytown, USA 12345"). 단일 행(address.formatted) 또는 구성 가능한 구성요소(거리, 도시, 주, 우편번호, 국가)로 다중 행 선택 가능. |
맞춤 사용자 데이터 필드
맞춤 사용자 데이터 필드는 기본 필드로 다루지 않는 추가 정보(예: 선호도, 관심사, 회사 규모, 기타 비즈니스 속성 등)를 수집하기 위한 사용자 정의 필드입니다.
맞춤 필드를 생성할 때는 사용자 데이터 키로 영숫자만 사용하세요(예: customData.companySize). 이후 필드 유형을 설정하고, 추가 속성을 필요에 맞게 커스터마이즈할 수 있습니다.
사용자 생성 후 맞춤 사용자 데이터를 조회 및 수정하는 방법은 사용자 데이터 구조를 참고하세요.
필드 유형
필드는 단순성에 따라 다음과 같이 분류할 수 있습니다:
- 기본형: 텍스트, 숫자, 날짜, 체크박스(불리언), 드롭다운(단일 선택), URL, 정규식.
- 복합형: 전체 이름, 주소.
공통 속성
| 속성 | 적용 대상 | 비고 |
|---|---|---|
| 라벨 | 전체 | 사용자에게 표시되는 이름. 값이 있거나 포커스 시 상단에 표시됩니다. 필수 입력 항목입니다. |
| 플레이스홀더 | 전체(체크박스 제외) | 라벨이 떠 있을 때 보이는 인라인 힌트(예시 텍스트/포맷 안내). |
| 설명 | 전체(체크박스 제외) | 필드 하단에 표시되는 추가 안내 또는 긴 설명. |
| 필수 여부 | 전체(체크박스 제외) | 활성화 시 비어 있으면 제출이 차단됩니다. 비활성화 시 라벨에 (선택) 태그가 추가됩니다. |
유형별 설정
| 유형 | 설정 가능 항목 | 비고 |
|---|---|---|
| 텍스트 | 최소/최대 길이 | 사용자 입력 텍스트의 최소 및 최대 길이 제한. |
| 숫자 | 최소/최대 값 | 입력 값의 최소 및 최대 숫자 범위 제한. |
| 날짜 | 날짜 형식(프리셋/사용자 지정) | 프리셋 형식(MM/dd/yyyy, dd/MM/yyyy, yyyy-MM-dd) 중 선택. 플레이스홀더 변경 시 기본 상호작용이 덮어써집니다. 또는 date-fns 패턴 완전 지원. |
| 체크박스 | 기본 값 | 체크(참) / 해제(거짓). |
| 드롭다운(선택) | 옵션 목록(1개 이상) | 한 줄에 값:라벨 형식 사용. 라벨 생략 시 값이 표시됩니다. |
| URL | 해당 없음 | 해당 없음 |
| 정규식 | 정규 표현식 | 검증 패턴(앞/뒤 슬래시 생략). 예: SSN용 ^\d3-\d2-\d4$. |
| 주소 | 구성요소 | 단일 또는 다중 행; 하위 구성요소: 거리, 도시, 주, 우편번호, 국가. |
| 전체 이름 | 구성요소 | 하위 구성요소: 이름, 중간 이름, 성. |
검증
필드 검증은 회원가입 마지막 단계에서 사용자 제출 시 수행됩니다. 다음 항목이 적용됩니다:
- 필수 입력 여부(체크박스 제외)
- 길이 제한(텍스트)
- 숫자 범위(숫자)
- 패턴 일치(정규식, 날짜 형식, URL, 선택 옵션 포함 여부)
- URL 구조(기본 구문 검증, 실제 접근성은 아님)
복합 필드인 address와 fullname의 하위 구성요소에도 동일한 검증 기준이 적용됩니다.
현지화
Logto는 firstName, lastName, gender, birthdate 등 기본 사용자 데이터 필드에 대해 시스템 수준 번역을 제공합니다. 이 필드의 라벨은 Logto 콘솔에서 설정할 수 있습니다.
Logto > 로그인 & 계정 > 콘텐츠에서 직접 번역을 제공하여 라벨을 덮어쓸 수 있습니다.
맞춤 필드는 사용자가 입력한 라벨, 플레이스홀더, 설명에 전적으로 의존합니다. 맞춤 필드 현지화는 UI 직접 구현 또는 문의하기를 통해 피드백을 남겨주시면 지원합니다.
Management API (주요 엔드포인트)
| 메서드 | 엔드포인트 | 목적 |
|---|---|---|
| GET | /api/custom-profile-fields | 모든 필드 목록 조회 |
| GET | /api/custom-profile-fields/:name | 이름으로 단일 필드 정의 조회 |
| POST | /api/custom-profile-fields | 필드 생성 |
| POST | /api/custom-profile-fields/batch | 일괄 생성(요청당 최대 20개) |
| PUT | /api/custom-profile-fields/:name | 이름 및 전체 데이터셋으로 필드 업데이트 |
| DELETE | /api/custom-profile-fields/:name | 필드 삭제 |
| POST | /api/custom-profile-fields/properties/sie-order | 로그인 경험에서 필드 순서 업데이트 |
Account Center에서 프로필 필드 표시
여기서 정의한 맞춤 프로필 필드는 기본 제공 Account Center 프로필 페이지에도 표시할 수 있어, 사용자가 회원가입 후 프로필 데이터를 조회 및 수정할 수 있습니다. 설정 방법은 다음과 같습니다:
-
콘솔 > 로그인 & 계정 > Account center
로 이동하세요. - 관련 필드 권한(프로필: 기본 제공 필드, 맞춤 데이터: 맞춤 필드)이
Edit또는ReadOnly로 설정되어 있는지 확인하세요. - 기본 제공 UI 통합 카드에서 노출할 프로필 필드를 선택기에서 추가하고, 드래그하여 순서를 변경하세요.
자세한 내용은 프로필 필드 구성을 참고하세요.
모범 사례
- 회원가입 시 필수 데이터만 수집하고, 추가 정보는 추후 프로필 완성 단계로 미루세요.
- 구조화된 데이터(주소, 전체 이름)는 복합 필드를 사용해 일관성과 현지화를 확보하세요.
- 포맷이 중요한 필드(정규식, 날짜, 숫자 범위)는 명확한 예시/플레이스홀더를 제공하세요.
자주 묻는 질문
프로필 필드가 기존 사용자 데이터를 수집하나요?
아니요, 신규 사용자 등록 마지막 단계에서만 정보를 수집합니다.
필드를 삭제하면 사용자 데이터도 삭제되나요?
아니요, 기존 사용자 데이터는 삭제되지 않습니다. 최종 사용자 경험에서 회원가입 폼에서만 해당 필드가 제거됩니다.
국가를 일반 텍스트 필드 대신 제어된 목록으로 수집할 수 있나요?
네, "국가" 구성요소를 표준화된 옵션이 있는 "드롭다운(단일 선택)" 필드로 전환할 수 있습니다.