Introducción
Abre una conexión WebSocket en tiempo real para recibir contenido, actualizaciones de pedidos y de usuarios sin necesidad de sondeo.
Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/events/introduction
🎯 ¿Qué hace este módulo?
El módulo WS (WebSocket) te permite recibir notificaciones en tiempo real - actualizaciones de contenido, cambios en pedidos, acciones de usuarios - estableciendo conexiones persistentes para obtener actualizaciones instantáneas sin sondeo, habilitando características en vivo como notificaciones, chat en vivo y paneles de control en tiempo real.
Piénsalo como tu sistema de notificación en tiempo real - en lugar de preguntar repetidamente "¿hay algo nuevo?" (sondeo), WebSocket mantiene una conexión abierta y el servidor te envía actualizaciones al instante cuando ocurren eventos.
📖 Explicación Simple
Cada aplicación moderna necesita actualizaciones en tiempo real:
- 🔔 Notificaciones en Vivo - Alertas instantáneas cuando algo sucede
- 💬 Chat en Vivo - Mensajería en tiempo real entre usuarios
- 📊 Paneles de Control en Vivo - Estadísticas y métricas que se actualizan automáticamente
- 🛒 Actualizaciones de Pedidos - Cambios de estado de pedidos instantáneos
- 📝 Actualizaciones de Contenido - Cambios y publicaciones de contenido en vivo
- 👥 Actividad del Usuario - Presencia y acciones de usuarios en tiempo real
- 🔄 Sincronización de Datos - Sincronización automática entre dispositivos
El problema con el sondeo (solicitudes repetidas):
// ❌ Bad - Polling every 5 seconds
setInterval(async () => {
const orders = await Orders.getOrders();
// Check if anything changed
// Wastes bandwidth, delays updates, server load
}, 5000);
Problemas:
- 🔋 Consumo de batería - Solicitudes constantes desperdician energía
- 📡 Desperdicio de red - La mayoría de las solicitudes devuelven "sin cambios"
- ⏱️ Actualizaciones retrasadas - Retraso de hasta 5 segundos
- 🖥️ Carga del servidor - Solicitudes innecesarias cada pocos segundos
La solución WebSocket:
// ✅ Good - Real-time WebSocket connection
const { WS } = defineOneEntry('https://your-site.oneentry.cloud', {
token: 'your-app-token'
});
// connect() returns a socket.io Socket (requires an authorized user)
const socket = await WS.connect();
// Listen for events with socket.on(...)
socket.on('my_event', (payload) => {
console.log('Update received!', payload);
// Instant notification, no polling!
});
Beneficios:
- 🔋 Eficiente - Conexión persistente única
- 📡 En tiempo real - Actualizaciones instantáneas, sin retraso
- ⏱️ Baja latencia - Entrega de notificaciones en menos de un segundo
- 🖥️ Carga reducida - El servidor envía actualizaciones solo cuando es necesario
✨ Conceptos Clave
¿Qué es WebSocket?
WebSocket es una conexión bidireccional persistente entre cliente y servidor:
- Conexión Persistente - Se mantiene abierta, sin apretón de manos repetidos
- Bidireccional - Tanto el cliente como el servidor pueden enviar mensajes
- En Tiempo Real - Entrega instantánea de mensajes
- Basado en Eventos - Escucha eventos con
socket.on(...) - Eficiente - Bajo consumo en comparación con el sondeo HTTP
WebSocket vs Sondeo HTTP
| Característica | WebSocket | Sondeo HTTP |
|---|---|---|
| Conexión | Persistente (se mantiene abierta) | Conexiones repetidas |
| Latencia | Menos de un segundo | Depende del intervalo (2-30s) |
| Eficiencia | Muy eficiente | Desperdiciador (muchas respuestas vacías) |
| Carga del Servidor | Baja (solo eventos) | Alta (solicitudes constantes) |
| Uso de Batería | Bajo | Alto (dispositivos móviles) |
| Caso de Uso | Actualizaciones en tiempo real | Aceptable para actualizaciones no críticas |
Ciclo de Vida de la Conexión WebSocket
1. Client opens a connection
(const socket = await WS.connect())
↓
2. Connection established
(socket.on('connect', ...) fires)
↓
3. Client listens for events
(socket.on('my_event', callback))
↓
4. Server sends events when they occur
(Instant delivery)
↓
5. Client receives event messages
(Callback function executes)
↓
6. Connection stays open
(No reconnection needed)
↓
7. Client disconnects when done
(socket.disconnect())
Qué eventos llegan a través de la conexión
No hay un catálogo fijo de nombres de eventos de SDK. Los eventos se activan de acuerdo con la configuración de tu módulo de Eventos en el panel de administración (el evento debe tener habilitada la opción WebSocket). Escuchas un evento por su marcador con socket.on('<event_marker>', callback).
La carga útil depende de la fuente del evento. Campos de carga útil típicos (ver connect() para ejemplos completos):
| Campo de carga útil | Llega para | Contiene |
|---|---|---|
attributes | Cada evento | Los propios atributos del evento |
product | Eventos de catálogo (producto) | Atributos del producto más title |
user | Eventos de formulario de usuario | Campos del formulario de usuario |
order | Eventos de pedidos | id del pedido y atributos |
email / code | Formularios de registro / código | Campos adicionales del formulario |
¿Por qué usar el módulo WebSocket?
| Beneficio | Descripción |
|---|---|
| Actualizaciones en Tiempo Real | Notificaciones instantáneas, sin retraso por sondeo |
| Eficiente | Conexión única, bajo consumo |
| Amigable con la Batería | Sin sondeo constante en móviles |
| Escalable | El servidor envía solo cuando es necesario |
| Impulsado por Eventos | Suscríbete a eventos específicos |
| Características en Vivo | Habilita chat, notificaciones, paneles de control |
📋 Lo Que Necesitas Saber
Gestión de Conexiones WebSocket
Las conexiones WebSocket deben ser gestionadas cuidadosamente:
Mejores prácticas:
- Verifica el estado de la conexión antes de suscribirte
- Implementa lógica de reconexión
- Maneja errores de conexión de manera adecuada
- Desconéctate cuando el usuario cierre sesión
Gestión de Suscripciones a Eventos
Suscríbete a eventos solo después de que la conexión esté establecida
Mejores prácticas:
- Usa funciones de callback nombradas para facilitar la desuscripción
- Suscríbete después de que la conexión esté abierta
- Desuscríbete cuando el componente se desmonte
- No te suscribas al mismo evento múltiples veces
Desuscripción de Eventos
Siempre desuscríbete cuando termines para prevenir fugas de memoria:
Mejores prácticas:
- Desuscríbete en funciones de limpieza
- Desconecta WebSocket cuando no sea necesario
- Previene fugas de memoria en SPAs
Estrategia de Reconexión
Implementa reconexión automática con retroceso exponencial:
Mejores prácticas:
- Usa retroceso exponencial para la reconexión
- Limita el número máximo de intentos de reconexión
- Restablece contadores en una conexión exitosa
- Permite desconexión manual sin reconexión
Estructura de la Carga Útil del Evento
Las cargas útiles de los eventos siguen una estructura consistente:
Mejores prácticas:
- Valida la estructura de la carga útil del evento
- Maneja campos faltantes de manera adecuada
- Verifica tipos de carga útil en TypeScript
Manejo de Errores
Implementa un manejo de errores integral:
Mejores prácticas:
- Captura errores en los controladores de eventos
- Registra errores para depuración
- Muestra mensajes de error amigables para el usuario
- No dejes que los errores hagan que la aplicación se bloquee
Optimización del Rendimiento
Optimiza el rendimiento de WebSocket:
Mejores prácticas:
- Limita eventos de alta frecuencia
- Agrupa múltiples actualizaciones
- Debounce actualizaciones de UI
- Evita operaciones costosas en los controladores
💡 Notas Importantes
⚠️ Gestión del Estado de Conexión
Siempre verifica el estado de la conexión antes de suscribirte
🔄 Manejo de Reconexiones
Las conexiones WebSocket pueden caerse inesperadamente:
- Cambios de red (WiFi a celular)
- Reinicios del servidor
- Tiempo de espera por inactividad
Siempre implementa lógica de reconexión
🧹 Prevención de Fugas de Memoria
Desuscríbete cuando termines para prevenir fugas de memoria
🔒 Seguridad
Las conexiones WebSocket están autenticadas:
- Autenticación basada en token (igual que en la API REST)
- Protocolo WebSocket Seguro (WSS)
- No es necesario enviar el token con cada mensaje
Mejores prácticas:
- Usa WSS (WebSocket seguro) en producción
- No expongas datos sensibles en los controladores de eventos
- Valida las cargas útiles de los eventos antes de procesarlas
📱 Consideraciones para Móviles
WebSocket en dispositivos móviles:
- Uso de batería (eficiente, pero conexión persistente)
- Las conexiones en segundo plano pueden ser terminadas
- Cambios de red requieren reconexión
Mejores prácticas:
- Reconéctate cuando la aplicación vuelva a primer plano
- Maneja cambios en el estado de la red
- Considera el sondeo para actualizaciones no críticas en móviles
📊 Tabla de Referencia Rápida
| Método | Descripción | Caso de Uso |
|---|---|---|
| connect() | Conectar al servidor WebSocket | Establecer conexión |
🔐
connect()requiere un usuario autorizado — autentica primero a través de AuthProvider. Después de conectar, adjunta controladores de eventos consocket.on(...).
❓ Preguntas Comunes (FAQ)
¿Cómo me conecto al servidor WebSocket?
Usa WS.connect() para abrir una conexión — devuelve un Socket de socket.io. Requiere un usuario autorizado, así que llama primero a AuthProvider.auth(...). Espera el evento connect antes de confiar en el socket, luego adjunta controladores con socket.on('<event_marker>', callback). La conexión está autenticada con el token de acceso del usuario más tu token de aplicación de defineOneEntry().
¿A qué eventos puedo suscribirme?
No hay una lista fija de eventos de SDK. Los eventos están definidos por la configuración de tu módulo de Eventos en el panel de administración (con la opción WebSocket habilitada), y escuchas un evento por su marcador con socket.on('<event_marker>', callback). Consulta connect() para ejemplos de carga útil (producto, usuario, pedido, formulario).
¿Cómo manejo caídas de conexión?
Implementa reconexión automática con retroceso exponencial. Escucha los eventos disconnect y connect_error de socket.io, luego intenta reconectar después de un retraso (por ejemplo, 1s, 2s, 4s, 8s, hasta un máximo de 30s). Restablece el contador de retraso en una connect exitosa. (socket.io también reconecta automáticamente por defecto).
¿Debería usar WebSocket o sondeo para mi aplicación?
Usa WebSocket para características en tiempo real (chat en vivo, notificaciones, paneles de control) donde las actualizaciones instantáneas son importantes. Usa sondeo para actualizaciones no críticas o cuando las conexiones WebSocket son problemáticas (firewalls restrictivos, modo de fondo en móviles).
¿Cómo prevengo fugas de memoria con suscripciones WebSocket?
Siempre desuscríbete de eventos cuando los componentes se desmonten o cuando la conexión ya no sea necesaria. En React, usa funciones de limpieza en useEffect. En Vue, usa el hook del ciclo de vida beforeUnmount.
¿Puedo usar WebSocket en dispositivos móviles?
Sí, pero ten en cuenta que el sistema operativo móvil puede terminar conexiones WebSocket en segundo plano. Reconéctate cuando la aplicación vuelva a primer plano. Considera el impacto en la batería de las conexiones persistentes en dispositivos móviles.
🎓 Mejores Prácticas
- Verifica el estado de la conexión - Suscríbete solo después de que la conexión se abra
- Implementa reconexión - Reconexión automática al desconectar con retroceso exponencial
- Desuscríbete en limpieza - Desconecta controladores (
socket.off) ysocket.disconnect()para prevenir fugas de memoria en SPAs - Maneja errores de manera adecuada - Captura errores en los controladores de eventos
- Limita eventos de alta frecuencia - Evita abrumar la UI con actualizaciones
- Valida cargas útiles de eventos - Verifica la estructura de datos antes de procesar
- Usa callbacks nombrados - Más fácil de desuscribirse y depurar
- Registra el estado de la conexión - Rastrea eventos de apertura/cierre/error para depuración
Definición del módulo WS
Puedes suscribirte a eventos a través de WebSocket para recibir notificaciones
const { WS } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
🔗 Documentación Relacionada
- Módulo de Pedidos - Eventos de pedidos para seguimiento de pedidos en tiempo real
- Módulo de Usuarios - Eventos de usuarios para notificaciones de registro
- Módulo de Pagos - Eventos de pagos para actualizaciones de transacciones
- API WebSocket