Coletar perfil do usuário

Além dos identificadores de autenticação e credenciais necessários para o login do usuário, seu aplicativo pode precisar coletar informações adicionais de perfil do usuário armazenadas no Logto para fácil recuperação via reivindicações JWT ou APIs, a fim de fornecer experiências de produto personalizadas. Você pode coletar dados do usuário pelos seguintes métodos:

• Durante o novo cadastro de usuário: Use o recurso Coletar perfil do usuário para adicionar uma etapa pronta chamada "Conte-nos sobre você" que coleta informações adicionais de perfil do usuário durante o cadastro. Novos usuários devem preencher todos os campos obrigatórios antes que o cadastro seja considerado concluído. Este documento foca nessa abordagem.

• Após o cadastro do usuário: Use a Account API para implementar experiências de autoatendimento durante fluxos de onboarding, centros de conta ou ao longo da jornada de uso do produto para atualizar informações do perfil do usuário.

Principais benefícios

O recurso Coletar perfil do usuário permite que você reúna informações adicionais do usuário durante a experiência de cadastro do usuário final. Recomendamos coletar apenas as informações essenciais necessárias para o seu produto, a fim de evitar fluxos de cadastro longos que possam impactar as taxas de conversão.

Este recurso permite que você:

• Capture dados abrangentes do usuário: Colete qualquer dado do usuário para fins de negócio ou conformidade, incluindo propriedades padrão do usuário OIDC e dados personalizados.

• Personalização flexível de campos: Escolha entre vários tipos de campo, incluindo texto, número, data, caixa de seleção, menu suspenso (select), URL e validação por regex para atender aos seus requisitos específicos de dados.

• Experiência do usuário otimizada: Personalize a exibição com rótulos, descrições, placeholders e regras de validação. Configure campos como obrigatórios ou opcionais conforme as necessidades do seu negócio.

• Configurações de campo integradas: Use campos de dados básicos pré-configurados para propriedades comuns do usuário com configuração plug-and-play. Aproveite campos compostos (endereço, nome completo) para coletar dados estruturados de forma eficiente em uma única etapa.

Início rápido

1. Acesse Console Logto > Experiência de Login > Coletar perfil do usuário.
2. Clique em "Adicionar campos de perfil" e escolha um campo integrado ou defina um dado personalizado (chave alfanumérica) para criar.
3. Abra os detalhes do campo para definir tipo, rótulo, descrição, obrigatoriedade e configurações específicas do tipo (comprimento, intervalo, formato, opções, etc.). Clique em "Salvar alterações".
4. Volte para Experiência de login > Coletar perfil do usuário, arraste e solte os campos para reordená-los, e as alterações serão aplicadas automaticamente.
5. Teste a experiência do usuário com o Logto live preview ou seu app de teste. Seja criando uma nova conta via identificador (email / número de telefone / nome de usuário), login social ou SSO corporativo (Enterprise SSO), todos verão a página "Conte-nos sobre você" durante o cadastro.

Tipos de dados do usuário

Os dados do usuário podem ser visualizados em cada perfil de usuário. Para uma visão geral completa de todas as categorias de dados do usuário, consulte a documentação de estrutura de dados do usuário. O recurso Coletar perfil do usuário permite reunir tanto dados básicos quanto dados personalizados durante o cadastro.

Campos básicos de dados do usuário

Os campos básicos de dados do usuário fornecidos pelo Logto são armazenados diretamente na propriedade user ou user.profile. Esses campos vêm com valores de configuração padrão e traduções i18n, prontos para uso imediato após a criação. Você também pode personalizar tipos e parâmetros dos campos conforme suas necessidades.

Nome do campo	Chave do dado do usuário	Descrição
Nome	user.name	Nome completo do usuário em formato exibível, incluindo todos os componentes do nome (ex: "Jane Doe").
Nome completo	user.profile.givenName user.profile.middleName user.profile.familyName	Nome legal completo do usuário. Combina de forma flexível familyName, givenName e middleName conforme configuração.
Apelido	user.profile.nickname	Nome casual ou familiar do usuário, que pode ser diferente do nome legal.
Data de nascimento	user.profile.birthdate	Data de nascimento do usuário em formato especificado (ex: "MM-dd-aaaa").
Gênero	user.profile.gender	Gênero autoidentificado do usuário (ex: "Feminino", "Masculino", "Prefiro não dizer").
Perfil	user.profile.profile	URL da página de perfil legível do usuário (ex: perfil em rede social).
Website	user.profile.website	URL do site pessoal ou blog do usuário.
Endereço	user.profile.address.formatted user.profile.address.streetAddress user.profile.address.region user.profile.address.zoneinfo user.profile.address.postalCode user.profile.address.country	Endereço completo do usuário (ex: "Rua Principal 123, Cidade, Brasil 12345"). Escolha entre linha única (address.formatted) ou multi-linha com componentes configuráveis (rua, cidade, estado, CEP, país).

Campos personalizados de dados do usuário

Campos personalizados de dados do usuário são campos definidos pelo usuário que capturam informações adicionais não cobertas pelos campos básicos, como preferências, interesses, tamanho da empresa ou outros atributos específicos do negócio.

Ao criar campos personalizados, use apenas caracteres alfanuméricos para a chave do dado do usuário (ex: customData.companySize). Você pode então configurar o tipo de campo e personalizar propriedades adicionais conforme suas necessidades.

Para mais informações sobre como recuperar e atualizar dados personalizados após a criação do usuário, veja estrutura de dados do usuário.

Tipos de campo

Podemos categorizar os campos de forma simples:

• Primitivos: Texto, Número, Data, Caixa de seleção (Booleano), Menu suspenso (Seleção única), URL, Expressão regular.
• Compostos: Nome completo, Endereço.

Propriedades comuns

Propriedade	Aplica-se a	Observações
Rótulo	Todos	Nome exibido aos usuários. Flutua para o topo quando o campo tem valor ou está em foco. Campo obrigatório.
Placeholder	Todos (exceto Checkbox)	Dica inline visível quando o rótulo está flutuando (exemplo de texto / orientação de formatação).
Descrição	Todos (exceto Checkbox)	Texto de apoio abaixo do campo para instruções mais longas ou contexto extra.
Obrigatório	Todos (exceto Checkbox)	Se ativado, o envio é bloqueado quando vazio. Se desativado, uma tag (Opcional) é adicionada ao rótulo.

Configurações específicas por tipo

Tipo	Aspectos configuráveis	Observações
Texto	min / max comprimento	Limite o comprimento mínimo e máximo do texto inserido pelo usuário.
Número	min / max valor	Limite o intervalo numérico mínimo e máximo do valor inserido.
Data	Formato da data (pré-definido / personalizado)	Escolha formatos pré-definidos (MM/dd/aaaa, dd/MM/aaaa, aaaa-MM-dd). Alterar o placeholder substitui interações padrão. Ou use padrões totalmente personalizáveis do date-fns.
Caixa de seleção	Valor padrão	Marcado (Verdadeiro) / Desmarcado (Falso).
Menu suspenso (Select)	Lista de opções (≥1)	Use valor:rótulo por linha. Se o rótulo for omitido, o valor é exibido.
URL	N/A	N/A
Regex	Expressão regular	Padrão de validação (omita barras iniciais / finais). Ex: ^\d3-\d2-\d4$ para CPF.
Endereço	Componentes	Linha única ou multi-linha; subcomponentes: rua, cidade, estado, CEP, país.
Nome completo	Componentes	Subcomponentes: primeiro, do meio, sobrenome.

Validação

A validação dos campos é realizada no envio do usuário na etapa final do cadastro. As seguintes verificações são aplicadas:

• Presença obrigatória (exceto Checkbox).
• Limites de comprimento (Texto).
• Intervalo numérico (Número).
• Correspondência de padrão (Regex, Data com formato, URL, pertencimento à opção Select).
• Estrutura de URL (validação sintática básica, não verifica acessibilidade).

Também se aplica aos subcomponentes dos dois campos compostos: address e fullname. Os componentes individuais também devem atender aos mesmos critérios de validação.

Localização

O Logto fornece traduções em nível de sistema para os campos básicos de dados do usuário, como firstName, lastName, gender e birthdate. O rótulo desses campos é configurável no Console Logto. Você pode substituir esses rótulos fornecendo suas próprias traduções em Logto > Experiência de Login > Conteúdo

Campos personalizados dependem totalmente dos rótulos, placeholders e descrições que você fornecer. Para localização de campos personalizados, você pode lidar com traduções usando Traga sua UI ou entre em contato conosco com seu feedback.

Management API (endpoints principais)

Método	Endpoint	Finalidade
GET	/api/custom-profile-fields	Listar todos os campos.
GET	/api/custom-profile-fields/:name	Buscar definição de campo único por nome.
POST	/api/custom-profile-fields	Criar um campo.
POST	/api/custom-profile-fields/batch	Criar em lote (≤20 itens por requisição).
PUT	/api/custom-profile-fields/:name	Atualizar campo por nome e conjunto completo.
DELETE	/api/custom-profile-fields/:name	Excluir um campo.
POST	/api/custom-profile-fields/properties/sie-order	Atualizar a ordem dos campos na Experiência de Login.

Boas práticas

• Colete apenas dados essenciais no cadastro; deixe informações desejáveis para a conclusão posterior do perfil.
• Use campos compostos para dados estruturados (endereço, nome completo) para consistência e localização.
• Forneça exemplos claros / placeholders para campos sensíveis a formato (regex, data, intervalos numéricos).

Perguntas frequentes

Os campos de perfil coletam dados de usuários existentes?

Não, eles coletam apenas informações da etapa final do cadastro de novos usuários.

E se eu excluir um campo? Isso remove os dados do usuário?

Não, isso não removerá os dados existentes do usuário. Apenas o campo será removido do formulário de cadastro na experiência do usuário final.

Posso coletar país com uma lista controlada em vez de um campo de texto comum?

Sim, você pode alterar o componente "País" para um campo "Menu suspenso (Seleção única)" com opções padronizadas.