Saltar al contenido principal

Introducción

🎯 ¿Qué hace este módulo?​

El módulo Users te permite gestionar usuarios registrados. En Platform OneEntry, hay herramientas necesarias para trabajar con usuarios registrados.

📖 Explicación Simple​

Cada aplicación necesita gestión de usuarios:

  • 📝 Perfiles de Usuario - Gestionar información del usuario
  • 💾 Datos de Usuario Personalizados - Almacenar datos específicos de la aplicación (objeto de estado)
  • 🔍 Búsqueda de Usuarios - Buscar y filtrar usuarios

✨ Conceptos Clave​

¿Qué es un Usuario?​

Un Usuario es una cuenta registrada en tu aplicación:

  • Información Básica - Nombre, correo electrónico, teléfono
  • Autenticación - Almacenamiento seguro de contraseñas
  • Objeto de Estado - Datos personalizados de la aplicación
  • Tiempos - Fecha de registro, último inicio de sesión
  • Estado - Activo, inactivo, bloqueado
  • Permisos - Roles de usuario y niveles de acceso

Estructura del Usuario​

Cada usuario tiene esta estructura:

{
  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
  total: "1"                                // Total count (for pagination)
}

Campos Clave:

  • id - Identificador único del usuario
  • identifier - Inicio de sesión del usuario (correo electrónico, teléfono, nombre de usuario)
  • authProviderIdentifier - Método de autenticación utilizado (correo electrónico, teléfono, etc.)
  • formData - Array de campos de formulario con la información del perfil del usuario
  • groups - Array de IDs de grupos para control de acceso
  • state - Objeto JSON personalizado para datos específicos de la aplicación

Obtener usuario con datos de estado personalizados​

Beneficios:

  • 🔒 Seguro - Hashing de contraseñas, autenticación segura
  • 📋 Validado - Validación de correo electrónico y datos
  • 🔄 Autenticado - Sesiones basadas en tokens
  • 💾 Persistente - Datos almacenados en la base de datos

Objeto de Estado del Usuario​

Puedes almacenar los datos necesarios para que tu aplicación funcione en un objeto de estado. Cuando cambies el usuario, agrega los datos necesarios al estado. Cuando se reciban posteriormente los datos del usuario, contendrán un objeto de estado.

Un ejemplo en el que agregamos información al usuario sobre cuántos pedidos ha realizado. Agrega un campo "orderCount" con el valor al objeto de estado.

El objeto de estado es un almacenamiento de datos personalizado por usuario:

Caso de UsoEjemplo de EstadoDescripción
E-commerce{ orderCount: 5, totalSpent: 499.99 }Rastrear historial de compras
Sitio de Contenido{ articlesRead: 25, bookmarks: [1,2,3] }Rastrear consumo de contenido
Aplicación Social{ postsCount: 42, followers: 150 }Rastrear métricas sociales
Gaming{ level: 15, score: 9500, achievements: [...] }Rastrear progreso en el juego
SaaS{ plan: 'premium', usage: 75 }Rastrear datos de suscripción

Flujo de Trabajo del Usuario​

1. User fills registration form
   (Email, password, name)
   ↓
2. createUser() called
   (OneEntry validates and hashes password)
   ↓
3. User account created
   (Stored in database)
   ↓
4. User logs in
   (authenticateUser() verifies credentials)
   ↓
5. Authentication token returned
   (Used for subsequent requests)
   ↓
6. Application updates user state
   (Custom data like orderCount)
   ↓
7. User data fetched as needed
   (getUserById() with current state)

¿Por qué usar el módulo de Usuarios?​

BeneficioDescripción
Autenticación SeguraHashing de contraseñas, gestión de tokens
Gestión de UsuariosLeer, actualizar, eliminar usuarios
Almacenamiento de Datos PersonalizadosObjeto de estado para datos específicos de la aplicación
Validación de Correo ElectrónicoComprobación automática del formato del correo
Prevención de DuplicadosPreviene el registro de correos duplicados
Gestión de SesionesAutenticación basada en tokens

📋 Lo Que Necesitas Saber​

Proveedor de Autorización​

Los usuarios en OneEntry se gestionan a través de un sistema de proveedor de autorización que maneja los mecanismos de registro y autenticación.

Puntos clave:

  • Los usuarios se registran a través de formularios configurados en el panel de administración de OneEntry
  • Cada usuario está asociado con un proveedor de autenticación (correo electrónico, teléfono, etc.)
  • Los datos del usuario se almacenan en campos de formulario definidos por formData
  • Metadatos adicionales se almacenan en el objeto state

El Objeto de Estado del Usuario es Flexible​

El objeto de estado puede almacenar cualquier dato JSON personalizado

Mejores prácticas:

  • Almacenar solo datos específicos de la aplicación
  • Mantener el objeto de estado organizado con objetos anidados
  • Actualizar todo el objeto de estado (dispersar datos existentes)
  • No almacenar datos sensibles en el estado

Seguridad de Contraseñas​

OneEntry maneja la seguridad de contraseñas automáticamente

Tu responsabilidad:

  • Hacer cumplir los requisitos de contraseña (longitud, complejidad)
  • Validar la contraseña en el lado del cliente antes de enviar
  • Nunca registrar contraseñas
  • Usar HTTPS para todas las solicitudes de autenticación

Gestión de Tokens de Autenticación​

Almacenar y usar tokens de autenticación de manera segura

Mejores prácticas para tokens:

  • Almacenar en cookies HTTP-only cuando sea posible
  • Usar tiempos de expiración cortos (1-2 horas)
  • Implementar tokens de actualización para sesiones largas
  • Limpiar el token al cerrar sesión
  • Nunca exponer tokens en URLs

Validación del Registro de Usuarios​

Siempre valida la entrada del usuario antes del registro

Actualizar el Estado del Usuario de Forma Segura​

Siempre preserva el estado existente al actualizar:

// ❌ Bad - Overwrites entire state
const userstate = {
  orderCount: 1
}

// ✅ Good - Preserve existing state
const userstate = {
  ...user.state, // Spread existing state
  orderCount: (user.state.orderCount || 0) + 1  // Update specific field
}

Prevención de Correos Electrónicos Duplicados​

OneEntry previene automáticamente el registro de correos electrónicos duplicados

Mejor práctica: Verifica el estado de error y muestra un mensaje amigable para el usuario.

Paginación de Usuarios​

Para bases de usuarios grandes, siempre paginar al obtener múltiples usuarios

💡 Notas Importantes​

Autorización Requerida​

La mayoría de los métodos de usuario requieren autorización a través del módulo AuthProvider. Asegúrate de autenticar al usuario primero antes de llamar a los métodos de gestión de usuarios.

Datos del Formulario de Usuario​

Los datos del usuario están estructurados de acuerdo con los formularios configurados en el panel de administración de OneEntry:

  • Cada usuario tiene un formIdentifier que hace referencia al formulario de registro utilizado
  • Los datos del usuario se almacenan en el array formData con marcadores, tipos y valores
  • Los tipos de campo admitidos incluyen: cadena, entero, flotante, fecha, fechaHora, hora, texto, textoConEncabezado, imagen, grupoDeImágenes, archivo, botónDeOpción, lista, entidad, intervaloDeTiempo

Directrices del Objeto de Estado​

Mejores prácticas para el objeto de estado:

  • Almacenar solo datos específicos de la aplicación
  • Mantener el estado organizado con objetos anidados
  • Actualizar todo el estado (dispersar datos existentes)
  • No almacenar datos sensibles (contraseñas, tokens)
  • No almacenar grandes datos binarios
  • Usar convenciones de nomenclatura consistentes

Notificaciones Push​

Usa addFCMToken() y deleteFCMToken() para gestionar tokens de Firebase Cloud Messaging para enviar notificaciones push a los usuarios.

Datos de Notificación​

Al actualizar usuarios, puedes proporcionar un objeto notificationData que contenga:

  • email - Dirección de correo electrónico para notificaciones
  • phonePush - Array de números de teléfono para notificaciones push
  • phoneSMS - Número de teléfono para notificaciones SMS

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
getUser()Obtener datos de usuario autorizadoObtener perfil de usuario actual
updateUser()Actualizar información del usuarioActualizaciones de perfil, cambios de estado
archiveUser()Archivar cuenta de usuarioEliminar suavemente la cuenta de usuario
deleteUser()Eliminar usuario permanentementeEliminar completamente la cuenta de usuario
addFCMToken()Agregar token FCM para notificaciones pushHabilitar notificaciones push
deleteFCMToken()Eliminar token FCMDeshabilitar notificaciones push

❓ Preguntas Comunes (FAQ)​

¿Qué es el objeto de estado del usuario y cómo debo usarlo?​

El objeto de estado es un almacenamiento JSON flexible para datos específicos de usuario de la aplicación. Úsalo para rastrear métricas personalizadas como conteos de pedidos, preferencias o progreso. Siempre dispersa el estado existente al actualizar para evitar sobrescribir otros datos.

¿Cómo actualizo la información del perfil del usuario?​

Usa updateUser() para modificar los datos del perfil del usuario. Puedes actualizar campos de datos del formulario, configuraciones de notificación y el objeto de estado. Recuerda autenticar al usuario primero usando el módulo AuthProvider.

¿Cuál es la diferencia entre archiveUser() y deleteUser()?​

archiveUser() es una eliminación suave que oculta al usuario pero preserva los datos (puede ser restaurado). deleteUser() elimina permanentemente al usuario y todos los datos asociados (no se puede deshacer). Usa la archivación a menos que necesites una eliminación completa de datos.

¿Cómo manejo las notificaciones push para los usuarios?​

Usa addFCMToken() para registrar un token de Firebase Cloud Messaging para el usuario. Esto permite enviar notificaciones push a sus dispositivos. Usa deleteFCMToken() cuando inicien sesión o desactiven las notificaciones.

¿Puedo almacenar datos sensibles en el objeto de estado del usuario?​

¡No! Nunca almacenes contraseñas, tokens, números de tarjetas de crédito u otros datos sensibles en el objeto de estado. No está cifrado específicamente para datos sensibles. Usa sistemas seguros y diseñados para información sensible.

¿Cómo obtengo datos del usuario después del registro?​

Después de un registro y autenticación exitosos, usa getUser() para obtener los datos del usuario autenticado, incluyendo su información de perfil y objeto de estado personalizado.

🎓 Mejores Prácticas​

  • Valida la entrada antes del registro - Verifica el formato del correo, la fortaleza de la contraseña
  • Usa HTTPS para la autenticación - Encripta todas las solicitudes de inicio de sesión
  • Implementa requisitos de contraseña - Mínimo 8 caracteres, mezcla de mayúsculas, números
  • Almacena tokens de manera segura - Cookies HTTP-only o almacenamiento seguro
  • Preserva el estado existente - Dispersa los datos existentes al actualizar el estado
  • Maneja correos duplicados - Captura errores 409 y muestra un mensaje amigable para el usuario
  • Implementa cierre de sesión - Limpia tokens y datos de sesión
  • Cachea datos de usuario - Reduce llamadas a la API para usuarios frecuentemente accedidos

Más información sobre la gestión de usuarios en el panel de administración de OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/users

Definición del módulo Users​


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

🔗 Documentación Relacionada​