跳到主要内容

收集用户资料

Cloud availabilityOSS availability

除了用户登录所需的认证 (Authentication) 标识符和凭证外，你的应用可能还需要收集额外的用户资料信息，这些信息存储在 Logto 中，便于通过 JWT 声明 (Claims) 或 API 检索，以提供个性化的产品体验。你可以通过以下方式收集用户数据：

  • 新用户注册时：使用 收集用户资料 功能，在注册过程中添加一个开箱即用的“告诉我们你的信息”步骤，收集额外的用户资料信息。新用户必须填写所有必填项后，注册才算完成。本篇文档重点介绍此方法。

  • 用户注册后：使用 Account API 在引导流程、账户中心或产品使用过程中实现自助体验，更新用户资料信息。

主要优势​

收集用户资料功能让你可以在终端用户注册体验中收集更多用户信息。我们建议只收集产品所需的关键信息，避免冗长的注册流程影响用户转化率。

此功能可以帮助你：

  • 获取全面的用户数据：为业务或合规目的收集任意用户数据，包括 OIDC 标准用户属性 和 自定义数据。

  • 灵活的字段自定义：可从多种字段类型中选择，包括文本、数字、日期、复选框、下拉框（单选）、URL 和正则校验，以满足你的数据需求。

  • 优化用户体验：通过标签、描述、占位符和校验规则自定义显示效果。可根据业务需求将字段设置为必填或选填。

  • 内置字段配置：为常见用户属性提供预配置的基础数据字段，开箱即用。利用复合字段（地址、全名）可在单步高效收集结构化数据。

快速开始​

  1. 进入 Logto 控制台 > 登录体验 > 收集用户资料。
  2. 点击“添加资料字段”，选择一个内置字段或定义一个自定义数据（字母数字键）进行创建。
  3. 打开字段详情，设置字段类型、标签、描述、必填标志及类型相关设置（长度、范围、格式、选项等）。点击“保存更改”。
  4. 返回 登录体验 > 收集用户资料，通过拖拽排序字段，变更会自动生效。
  5. 使用 Logto 实时预览 或你的测试应用体验用户流程。无论用户通过 标识符（邮箱 / 手机号 / 用户名）、社交登录 还是 企业单点登录 (SSO) 创建新账户，注册时都会看到“告诉我们你的信息”页面。
注册时收集用户资料

用户数据类型​

用户数据可在每个用户资料中查看。关于所有用户数据类别的完整概览，请参考 用户数据结构 文档。收集用户资料功能允许你在注册时收集基础用户数据和自定义用户数据。

基础用户数据字段​

Logto 提供的基础用户数据字段直接存储在 user 或 user.profile 属性中。这些字段自带默认配置值和 i18n 翻译，创建后即可直接使用。你也可以根据具体需求自定义字段类型和参数。

字段名称用户数据键描述
姓名user.name用户的全名，包含所有姓名组成部分（如 "Jane Doe"）。
全名user.profile.givenName
user.profile.middleName
user.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.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$ 用于 SSN。
地址组件单行或多行；子组件：街道、城市、州、省、邮编、国家。
全名组件子组件：名、中间名、姓。

校验​

字段校验在注册最后一步用户提交时进行。强制执行以下检查：

  • 必填校验（复选框除外）。
  • 长度限制（文本）。
  • 数值范围（数字）。
  • 模式匹配（正则、日期格式、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更新登录体验中的字段顺序。

最佳实践​

  • 注册时只收集必要数据，非核心信息可延后补全。
  • 使用复合字段（地址、全名）收集结构化数据，便于一致性和本地化。
  • 对格式敏感字段（正则、日期、数值范围）提供清晰示例 / 占位符。

常见问题​

资料字段会收集已有用户的数据吗？​

不会，只会收集新用户注册最后一步的信息。

如果我删除了一个字段，会删除用户数据吗？{what-if-i-delete-a-field-does-it-remove-the-user-data}​

不会，已有用户数据不会被删除。只是在终端用户注册表单中移除了该字段。

我可以用受控列表收集国家信息，而不是普通文本字段吗？{can-i-collect-country-with-a-controlled-list-instead-of-a-regular-text-field}​

可以，你可以将“国家”组件切换为带标准选项的“下拉框（单选）”字段。