사용자 프로필 수집
사용자 로그인에 필요한 인증 (Authentication) 식별자 및 자격 증명 외에도, 애플리케이션에서 개인화된 제품 경험을 제공하기 위해 Logto에 저장된 추가 사용자 프로필 정보를 수집해야 할 수 있습니다. 이 정보는 JWT 클레임 또는 API를 통해 쉽게 조회할 수 있습니다. 사용자 데이터를 수집하는 방법은 다음과 같습니다:
-
신규 사용자 등록 시: 사용자 프로필 수집 기능을 사용하여 회원가입 과정에서 추가 사용자 프로필 정보를 수집하는 "자기소개" 단계를 기본 제공으로 추가할 수 있습니다. 신규 사용자는 모든 필수 항목을 입력해야 등록이 완료됩니다. 이 문서는 이 방법에 중점을 둡니다.
-
사용자 등록 후: Account API를 사용하여 온보딩 플로우, 계정 센터, 또는 제품 사용 중에 셀프 서비스 방식으로 사용자 프로필 정보를 업데이트할 수 있습니다.
주요 이점
사용자 프로필 수집 기능을 통해 최종 사용자 등록 과정에서 추가 정보를 수집할 수 있습니다. 제품에 꼭 필요한 정보만 수집하여, 사용자 전환율에 영향을 줄 수 있는 긴 회원가입 과정을 피하는 것을 권장합니다.
이 기능을 통해 다음을 할 수 있습니다:
-
포괄적인 사용자 데이터 수집: OIDC 표준 사용자 속성 및 사용자 정의 데이터를 포함하여 비즈니스 또는 컴플라이언스 목적의 모든 사용자 데이터를 수집할 수 있습니다.
-
유연한 필드 커스터마이즈: 텍스트, 숫자, 날짜, 체크박스, 드롭다운 (선택), URL, 정규식 검증 등 다양한 필드 유형 중에서 선택하여 데이터 요구 사항에 맞게 설정할 수 있습니다.
-
최적화된 사용자 경험: 라벨, 설명, 플레이스홀더, 검증 규칙 등 표시 내용을 커스터마이즈할 수 있습니다. 비즈니스 요구에 따라 필드를 필수 또는 선택으로 설정할 수 있습니다.
-
내장 필드 구성: 일반 사용자 속성을 위한 사전 구성된 기본 데이터 필드를 플러그 앤 플레이 방식으로 사용할 수 있습니다. 복합 필드(주소, 전체 이름)를 활용하여 한 번에 구조화된 데이터를 효율적으로 수집할 수 있습니다.
빠른 시작
-
Logto 콘솔 > 로그인 경험 > 사용자 프로필 수집
로 이동하세요. - "프로필 필드 추가"를 클릭하고 기본 내장 필드를 선택하거나 사용자 정의 데이터 (영숫자 키)를 정의하여 생성하세요.
- 필드 상세 설정에서 필드 유형, 라벨, 설명, 필수 여부, 유형별 설정(길이, 범위, 형식, 옵션 등)을 지정한 후 "변경 사항 저장"을 클릭하세요.
- 로그인 경험 > 사용자 프로필 수집 화면에서 필드를 드래그 앤 드롭하여 순서를 변경하면, 변경 사항이 자동으로 적용됩니다.
- Logto 라이브 프리뷰 또는 테스트 앱에서 사용자 경험을 테스트하세요. 사용자가 식별자(이메일/휴대폰 번호/사용자명), 소셜 로그인, 또는 엔터프라이즈 SSO를 통해 새 계정을 생성할 때 모두 회원가입 과정에서 "자기소개" 페이지를 보게 됩니다.
사용자 데이터 유형
사용자 데이터는 각 사용자 프로필에서 확인할 수 있습니다. 모든 사용자 데이터 카테고리에 대한 전체 개요는 사용자 데이터 구조 문서를 참고하세요. 사용자 프로필 수집 기능을 통해 회원가입 시 기본 사용자 데이터와 사용자 정의 데이터를 모두 수집할 수 있습니다.
기본 사용자 데이터 필드
Logto에서 제공하는 기본 사용자 데이터 필드는 user 또는 user.profile 속성에 직접 저장됩니다. 이 필드들은 기본 구성 값과 i18n 번역이 적용되어 생성 즉시 바로 사용할 수 있습니다. 또한, 필요에 따라 필드 유형과 파라미터를 커스터마이즈할 수 있습니다.
| 필드명 | 사용자 데이터 키 | 설명 |
|---|---|---|
| 이름 | user.name | 모든 이름 구성 요소를 포함한 사용자의 표시용 전체 이름 (예: "홍길동"). |
| 전체 이름 | 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번지"). 단일 행(address.formatted) 또는 구성 요소별(거리, 도시, 주, 우편번호, 국가)로 선택 가능. |
사용자 정의 데이터 필드
사용자 정의 데이터 필드는 기본 필드로 다루지 않는 추가 정보(예: 선호도, 관심사, 회사 규모, 기타 비즈니스 속성 등)를 수집하기 위한 사용자 지정 필드입니다.
사용자 정의 필드를 생성할 때는 사용자 데이터 키로 영숫자만 사용하세요(예: customData.companySize). 이후 필드 유형을 설정하고, 필요에 따라 추가 속성을 커스터마이즈할 수 있습니다.
사용자 생성 후 사용자 정의 데이터를 조회 및 업데이트하는 방법은 사용자 데이터 구조 문서를 참고하세요.
필드 유형
필드는 단순하게 다음과 같이 분류할 수 있습니다:
- 기본형: 텍스트, 숫자, 날짜, 체크박스(불리언), 드롭다운(단일 선택), URL, 정규식.
- 복합형: 전체 이름, 주소.
공통 속성
| 속성 | 적용 대상 | 비고 |
|---|---|---|
| 라벨 | 전체 | 사용자에게 표시되는 이름. 값이 있거나 포커스 시 상단에 떠오릅니다. 필수 입력 항목입니다. |
| 플레이스홀더 | 전체(체크박스 제외) | 라벨이 떠 있을 때 보이는 인라인 힌트(예시 텍스트/형식 안내). |
| 설명 | 전체(체크박스 제외) | 필드 하단에 표시되는 추가 안내 또는 긴 설명. |
| 필수 여부 | 전체(체크박스 제외) | 활성화 시 비어 있으면 제출이 차단됩니다. 비활성화 시 라벨에 (선택) 태그가 추가됩니다. |
유형별 설정
| 유형 | 설정 가능 항목 | 비고 |
|---|---|---|
| 텍스트 | 최소/최대 길이 | 사용자 입력 텍스트의 최소/최대 길이 제한. |
| 숫자 | 최소/최대 값 | 입력 값의 숫자 범위 제한. |
| 날짜 | 날짜 형식(프리셋/사용자 지정) | 프리셋 형식(MM/dd/yyyy, dd/MM/yyyy, yyyy-MM-dd) 중 선택. 플레이스홀더 변경 시 기본 상호작용이 덮어쓰기 됩니다. 또는 date-fns 패턴 사용 가능. |
| 체크박스 | 기본값 | 체크(참) / 해제(거짓). |
| 드롭다운(선택) | 옵션 목록(1개 이상) | 한 줄에 값:라벨 형식 사용. 라벨 생략 시 값이 표시됩니다. |
| URL | 해당 없음 | 해당 없음 |
| 정규식 | 정규 표현식 | 검증 패턴(앞/뒤 슬래시 생략). 예: ^\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 | 로그인 경험 내 필드 순서 변경 |
모범 사례
- 회원가입 시 꼭 필요한 데이터만 수집하고, 추가 정보는 추후 프로필 완성 단계로 미루세요.
- 구조화된 데이터(주소, 전체 이름)는 복합 필드를 사용하여 일관성과 현지화를 확보하세요.
- 형식에 민감한 필드(정규식, 날짜, 숫자 범위)는 명확한 예시/플레이스홀더를 제공하세요.
자주 묻는 질문
프로필 필드가 기존 사용자 데이터를 수집하나요?
아니요, 신규 사용자 등록 마지막 단계에서만 정보를 수집합니다.
필드를 삭제하면 사용자 데이터도 삭제되나요?
아니요, 기존 사용자 데이터는 삭제되지 않습니다. 최종 사용자 경험에서 회원가입 폼에서만 해당 필드가 제거됩니다.
국가 정보를 일반 텍스트 필드 대신 선택형 목록으로 수집할 수 있나요?
네, "국가" 구성 요소를 표준화된 옵션이 있는 "드롭다운(단일 선택)" 필드로 전환할 수 있습니다.