收集使用者資料

除了用於使用者登入的驗證 (Authentication) 識別碼與憑證外，你的應用程式可能還需要收集額外的使用者資料，這些資料會儲存在 Logto，方便透過 JWT 宣告 (Claims) 或 API 取得，以提供個人化的產品體驗。你可以透過以下方式收集使用者資料：

• 新使用者註冊時：使用 收集使用者資料 功能，在註冊流程中新增現成的「告訴我們關於你自己」步驟，收集額外的使用者資料。新使用者必須填寫所有必填欄位，註冊才算完成。本文件重點介紹此方法。

• 使用者註冊後：使用 Account API 在導覽流程、帳號中心或產品使用過程中，實作自助式體驗以更新使用者資料。

主要優勢

收集使用者資料 功能讓你能在終端使用者註冊體驗中收集額外資訊。我們建議僅收集產品所需的必要資訊，避免冗長的註冊流程影響使用者轉換率。

此功能可讓你：

• 收集完整的使用者資料：可收集任何 使用者資料 以滿足業務或合規需求，包括 OIDC 標準使用者屬性與 自訂資料。

• 彈性的欄位自訂：可從多種 欄位類型 選擇，包括文字、數字、日期、核取方塊、下拉選單（單選）、URL、正則驗證，以符合你的資料需求。

• 最佳化使用者體驗：可自訂顯示標籤、說明、預設提示與驗證規則。根據業務需求設定欄位為必填或選填。

• 內建欄位設定：提供常用使用者屬性的預設資料欄位，開箱即用。複合欄位（地址、全名）可一次性高效收集結構化資料。

快速開始

1. 前往 Logto 控制台 > 登入體驗 > 收集使用者資料。
2. 點擊「新增資料欄位」，選擇 內建欄位 或自訂 自訂資料（英數字鍵名）進行建立。
3. 開啟欄位詳情，設定欄位類型、標籤、說明、必填與類型專屬設定（長度、範圍、格式、選項等），點擊「儲存變更」。
4. 回到登入體驗 > 收集使用者資料，拖曳欄位調整順序，變更會自動套用。
5. 使用 Logto 即時預覽 或你的測試應用程式驗證體驗。無論使用者透過 識別碼（電子郵件 / 手機號碼 / 使用者名稱）、社交登入 或 企業級單一登入 (Enterprise SSO) 建立新帳號，註冊時都會看到「告訴我們關於你自己」頁面。

使用者資料類型

你可以在每個 使用者資料頁 查看使用者資料。完整的使用者資料分類請參閱 使用者資料結構 文件。收集使用者資料功能可於註冊時同時收集基本資料與自訂資料。

基本使用者資料欄位

Logto 提供的基本使用者資料欄位會直接儲存在 user 或 user.profile 屬性中。這些欄位具備預設設定值與 i18n 翻譯，建立後即可直接使用。你也可依需求自訂欄位類型與參數。

欄位名稱	使用者資料鍵名	說明
Name	user.name	使用者的全名，包含所有姓名組件（如 "Jane Doe"）。
Fullname	user.profile.givenName user.profile.middleName user.profile.familyName	使用者完整法定姓名。可依設定彈性組合 familyName、givenName、middleName。
Nickname	user.profile.nickname	使用者的暱稱，可能與法定姓名不同。
Birthdate	user.profile.birthdate	使用者的出生日期，格式可指定（如 "MM-dd-yyyy"）。
Gender	user.profile.gender	使用者自我認同的性別（如 "Female"、"Male"、"Prefer not to say"）。
Profile	user.profile.profile	使用者可讀取的人物頁面 URL（如社群媒體個人頁）。
Website	user.profile.website	使用者個人網站或部落格的 URL。
Address	user.profile.address.formatted user.profile.address.streetAddress user.profile.address.region user.profile.address.zoneinfo user.profile.address.postalCode user.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 完全自訂格式。
核取方塊	預設值	勾選（True）/ 未勾選（False）。
下拉選單（單選）	選項清單（≥1）	每行使用 value:label。若省略 label，則顯示 value。
URL	無	無
正則表達式	驗證模式	驗證規則（省略前後斜線）。如 ^\d3-\d2-\d4$ 用於美國社會安全號。
地址	組件	單行或多行；子組件：街道、城市、州、省、郵遞區號、國家。
全名	組件	子組件：名、中間名、姓。

驗證

欄位驗證會在註冊最後一步送出時執行，檢查內容如下：

• 必填檢查（核取方塊除外）。
• 長度限制（文字）。
• 數值範圍（數字）。
• 格式比對（正則、日期格式、URL、下拉選項）。
• URL 結構（基本語法驗證，不檢查可達性）。

同時適用於複合欄位（address、fullname）的子組件。每個子組件也需符合相同驗證規則。

在地化

Logto 為基本使用者資料欄位（如 firstName、lastName、gender、birthdate）提供系統級翻譯。這些欄位的標籤可在 Logto 控制台自訂。 你可在 Logto > 登入體驗 > 內容 提供自訂翻譯覆蓋這些標籤。

自訂欄位完全依賴你所設定的標籤、預設提示與說明。若需自訂欄位的多語系，建議使用 自帶 UI (Bring your 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	更新登入體驗中的欄位排序。

最佳實踐

• 註冊時僅收集必要資料，其他資訊可於後續補齊。
• 結構化資料（地址、全名）建議使用複合欄位，利於一致性與在地化。
• 格式敏感欄位（正則、日期、數值範圍）請提供清楚範例或預設提示。

常見問題

資料欄位會收集現有使用者資料嗎？

不會，僅會收集新使用者註冊最後一步的資訊。

如果我刪除欄位，會移除使用者資料嗎？

不會，既有使用者資料不會被移除。僅會從終端使用者註冊表單中移除該欄位。

我可以用受控清單收集國家，而不是一般文字欄位嗎？

可以，你可以將「國家」組件切換為「下拉選單（單選）」欄位，並設定標準選項。