Pular para o conteúdo principal

Introdução

Gerencie usuários registrados — busque perfis, atualize dados e gerencie o estado da conta.

Mais informações sobre gerenciamento de usuários no painel de administração do OneEntry: https://doc.oneentry.cloud/docs/category/users

🎯 O que este módulo faz?​

O módulo Users gerencia o usuário já autenticado: busca o perfil, atualiza os dados do formulário e o objeto state personalizado, arquiva ou exclui a conta, gerencia o carrinho e a lista de desejos por usuário (ou convidado) e registra tokens FCM para notificações push.

Registro e login não estão aqui — eles estão no módulo AuthProvider. O módulo Users trabalha com o usuário que o AuthProvider já autorizou.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


const { Users } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Busque o usuário atual e atualize seu objeto state personalizado (assume uma sessão autenticada — veja AuthProvider):

// Fetch the authorized user's profile and state.
const user = await Users.getUser("en_US");

console.log(user.id, user.identifier);

// Update the user, preserving existing state.
await Users.updateUser({
  formIdentifier: user.formIdentifier,
  formData: user.formData,
  state: { ...user.state, orderCount: (user.state.orderCount || 0) + 1 },
});

✨ Conceitos Chave​

O que é um Usuário?​

Um Usuário é uma conta registrada em sua aplicação:

  • Identificador - valor de login (email, telefone ou nome de usuário)
  • Auth Provider - o método de autenticação utilizado (authProviderIdentifier)
  • Form Data - campos de perfil definidos pelo formulário de registro (formData)
  • Grupos - array de IDs de grupos aos quais o usuário pertence
  • State Object - dados personalizados da aplicação

Estrutura do Usuário​

Cada usuário tem esta estrutura:

{
  id: 8,                                    // User ID
  identifier: 'test@test.ru',               // User identifier (email/login)
  authProviderIdentifier: 'email',          // Auth provider type
  formIdentifier: 'reg',                    // Registration form identifier
  formData: [                               // User profile data
    { marker: 'name_reg', type: 'string', value: 'Ivan' },
    { marker: 'phone_reg', type: 'string', value: '+19258382556' },
  ],
  groups: [1],                              // User groups for permissions
  state: {},                                // Custom application data
  moduleFormConfigs: [],                    // Additional form configurations
}

State Object​

Você pode armazenar qualquer dado específico da aplicação no objeto state por usuário. Quando você atualiza o usuário, adicione os dados que precisa ao state; chamadas subsequentes de getUser() retornam esses dados.

Caso de UsoExemplo de StateDescrição
E-commerce{ orderCount: 5, totalSpent: 499.99 }Rastrear histórico de compras
Conteúdo{ articlesRead: 25, bookmarks: [1,2,3] }Rastrear consumo de conteúdo
Jogos{ level: 15, score: 9500, achievements: [...] }Rastrear progresso no jogo
SaaS{ plan: 'premium', usage: 75 }Rastrear dados de assinatura

Sempre preserve o estado existente ao atualizar — espalhe-o para não perder outros campos:

// ❌ Bad - overwrites the entire state
const state = { orderCount: 1 };

// ✅ Good - preserve existing state
const state = {
  ...user.state,
  orderCount: (user.state.orderCount || 0) + 1,
};

📋 O que você precisa saber​

Autorização necessária​

Cada método de usuário requer uma sessão autorizada — autentique o usuário primeiro através do módulo AuthProvider. Os métodos de carrinho e lista de desejos também funcionam para convidados (veja a seção Carrinho e Lista de Desejos abaixo).

Dados do formulário do usuário​

Os dados do perfil do usuário seguem os formulários configurados no painel de administração do OneEntry:

  • Cada usuário tem um formIdentifier que referencia o formulário de registro utilizado.
  • Os campos de perfil estão no array formData como entradas marker / type / value.
  • Os tipos de campo suportados incluem: string, inteiro, float, data, dataHora, hora, texto, textoComCabeçalho, imagem, grupoDeImagens, arquivo, botãoDeOpção, lista, entidade, intervaloDeTempo.

Diretrizes para o objeto state​

  • Armazene apenas dados específicos da aplicação; não coloque senhas, tokens ou dados de cartão no state.
  • Mantenha organizado com objetos aninhados e nomes consistentes.
  • Atualize espalhando o state existente (veja acima) — nunca sobrescreva cegamente.

Dados de notificação​

Ao atualizar um usuário, você pode passar um objeto notificationData com canais de entrega:

  • email - endereço de email para notificações
  • phonePush - array de números de telefone para notificações push
  • phoneSMS - número de telefone para notificações SMS

Paginação​

Para listas de carrinho/lista de desejos e outras coleções, pagine os resultados em vez de carregar tudo de uma vez.

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
getUser() 🔐Obter dados do usuário autorizadoBuscar perfil do usuário atual
updateUser() 🔐Atualizar informações do usuárioAtualizações de perfil, mudanças de estado
archiveUser() 🔐Arquivar conta de usuárioExcluir suavemente a conta do usuário
deleteUser() 🔐Excluir usuário permanentementeExcluir a conta do usuário de forma definitiva
addFCMToken() 🔐Adicionar token FCM para notificações pushHabilitar notificações push
deleteFCMToken() 🔐Remover token FCMDesabilitar notificações push
getCart()Obter o carrinho do usuário ou convidadoLer o carrinho atual
setCart()Substituir todo o carrinhoSincronizar um carrinho do lado do cliente
addCartItem()Adicionar um item ao carrinhoAção "Adicionar ao carrinho"
removeCartItem()Remover um item do carrinhoAção "Remover do carrinho"
getWishlist()Obter a lista de desejos do usuário ou convidadoLer a lista de desejos atual
setWishlist()Substituir toda a lista de desejosSincronizar uma lista de desejos do lado do cliente
addWishlistItem()Adicionar um item à lista de desejosAção "Adicionar à lista de desejos"
removeWishlistItem()Remover um item da lista de desejosAção "Remover da lista de desejos"

🔐 marca métodos que requerem uma sessão de usuário autorizada (AuthProvider). Os métodos de carrinho e lista de desejos também funcionam para convidados.

🛒 Carrinho & Lista de Desejos​

Os métodos de carrinho e lista de desejos funcionam tanto para usuários autorizados quanto para convidados. Para um convidado, o SDK envia um cabeçalho x-guest-id para que o carrinho/lista de desejos esteja vinculado ao visitante anônimo correto - veja Modo convidado. Assim que um convidado faz login, os mesmos métodos operam nos dados do usuário autenticado.

Esses métodos também alimentam os blocos de personalização (como complemento de carrinho, carrinho similar e lista de desejos similar) e podem ser combinados com o rastreamento de atividade do usuário.

❓ Perguntas Comuns (FAQ)​

O que é o objeto state do usuário e como devo usá-lo?​

O objeto state é um armazenamento JSON flexível para dados específicos do usuário na aplicação. Use-o para rastrear métricas personalizadas como contagem de pedidos, preferências ou progresso. Sempre espalhe o estado existente ao atualizar para evitar sobrescrever outros dados.

Como atualizo as informações do perfil do usuário?​

Use updateUser() para modificar campos de dados do formulário, configurações de notificação e o objeto state. Autentique o usuário primeiro através do módulo AuthProvider.

Qual é a diferença entre archiveUser() e deleteUser()?​

archiveUser() é uma exclusão suave que marca o usuário para exclusão, mas preserva os dados. deleteUser() remove permanentemente a conta do usuário. Use arquivamento, a menos que você precise de remoção completa dos dados.

Como faço para gerenciar notificações push para usuários?​

Use addFCMToken() para registrar um token do Firebase Cloud Messaging para o usuário, habilitando notificações push em seus dispositivos. Use deleteFCMToken() quando eles fizerem logout ou desabilitarem notificações.

Como busco dados do usuário após o registro?​

Após o registro e autenticação bem-sucedidos via AuthProvider, chame getUser() para buscar o perfil do usuário autenticado e o objeto state personalizado.

🎓 Melhores Práticas​

  • Autentique primeiro - cada método de usuário requer uma sessão autorizada (veja o módulo AuthProvider).
  • Preserve o estado existente - espalhe os dados existentes ao atualizar o state.
  • Não armazene dados sensíveis no state - mantenha senhas, tokens e dados de cartão fora do state.
  • Cache os dados do usuário - reduza chamadas à API para dados acessados com frequência.

🔗 Documentação Relacionada​