跳至主要內容

收集使用者資料

Cloud availabilityOSS availability

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

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

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

主要優勢​

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

此功能可協助你：

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

  • 彈性欄位自訂：可從多種 欄位型態 選擇，包括文字、數字、日期、勾選框、下拉選單（單選）、URL 及正則驗證，滿足你的資料需求。

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

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

快速開始​

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

使用者資料型態​

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

基本使用者資料欄位​

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

欄位名稱使用者資料鍵名說明
Nameuser.name使用者的全名，包含所有組成部分（如「Jane Doe」）。
Fullnameuser.profile.givenName
user.profile.middleName
user.profile.familyName		使用者完整法定姓名。可依設定彈性組合 familyName、givenName、middleName。
Nicknameuser.profile.nickname使用者的暱稱，可能與法定姓名不同。
Birthdateuser.profile.birthdate使用者的出生日期，格式可自訂（如「MM-dd-yyyy」）。
Genderuser.profile.gender使用者自我認同的性別（如「女性」、「男性」、「不願透露」）。
Profileuser.profile.profile使用者可讀取的個人頁面 URL（如社群媒體個人檔案）。
Websiteuser.profile.website使用者個人網站或部落格的 URL。
Addressuser.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）每行 值:標籤。若省略標籤，則顯示值。
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更新登入體驗中的欄位排序。

最佳實踐​

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

常見問題​

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

不會，只會收集新使用者註冊最後一步填寫的資料。

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

不會，既有使用者資料不會被移除，只是該欄位不再出現在終端使用者註冊表單中。

我可以用下拉選單（受控列表）收集國家，而不是一般文字欄位嗎？​

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