Saltar al contenido principal

Introducción

🎯 ¿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 sondeos, habilitando características en vivo como notificaciones, chat en vivo y paneles 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 en Vivo - Estadísticas y métricas que se actualizan automáticamente
  • 🛒 Actualizaciones de Pedidos - Cambios instantáneos en el estado del pedido
  • 📝 Actualizaciones de Contenido - Cambios y publicaciones de contenido en vivo
  • 👥 Actividad del Usuario - Presencia y acciones del usuario 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:

  • 🔋 Desgaste 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'
});

// Subscribe to events
WS.subscribe('order.created', (order) => {
  console.log('New order received!', order);
  // Instant notification, no polling!
});

WS.subscribe('content.updated', (content) => {
  console.log('Content updated!', content);
  // Update UI immediately
});

Beneficios:

  • 🔋 Eficiente - Una única conexión persistente
  • 📡 En tiempo real - Actualizaciones instantáneas, sin retraso
  • ⏱️ Baja latencia - Entrega de notificaciones en menos de un segundo
  • 🖥️ Carga reducida - El servidor envía solo cuando es necesario

✨ Conceptos Clave​

¿Qué es WebSocket?​

WebSocket es una conexión bidireccional persistente entre el cliente y el 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 - Suscríbete a eventos específicos
  • Eficiente - Bajo overhead en comparación con el sondeo HTTP

WebSocket vs Sondeo HTTP​

CaracterísticaWebSocketSondeo HTTP
ConexiónPersistente (se mantiene abierta)Conexiones repetidas
LatenciaMenos de un segundoDepende del intervalo (2-30s)
EficienciaMuy eficienteDesperdiciador (muchas respuestas vacías)
Carga del ServidorBaja (solo eventos)Alta (solicitudes constantes)
Uso de BateríaBajoAlto (dispositivos móviles)
Caso de UsoActualizaciones en tiempo realAceptable para actualizaciones no críticas

Ciclo de Vida de la Conexión WebSocket​

1. Client connects to WebSocket server
   (WS.connect())
   ↓
2. Connection established
   (onOpen event fires)
   ↓
3. Client subscribes to events
   (WS.subscribe('event.name', 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
   (WS.disconnect())

Eventos Comunes de WebSocket​

Tipo de EventoDescripciónCaso de Uso Ejemplo
order.createdNuevo pedido realizadoMostrar notificación "¡Nuevo Pedido!"
order.updatedCambió el estado del pedidoActualizar el estado del pedido en la interfaz
content.publishedNuevo contenido publicadoActualizar la lista de contenido
content.updatedContenido editadoActualizar el contenido mostrado
user.registeredNuevo usuario registradoMostrar nuevo usuario en el panel de administración
payment.completedPago procesadoActualizar el estado del pedido a "Pagado"
product.outOfStockProducto fuera de stockMostrar insignia "Agotado"

¿Por qué usar el módulo WebSocket?​

BeneficioDescripción
Actualizaciones en Tiempo RealNotificaciones instantáneas, sin retraso por sondeo
EficienteUna única conexión, bajo overhead
Amigable con la BateríaSin sondeo constante en móviles
EscalableEl servidor envía solo cuando es necesario
Impulsado por EventosSuscríbete a eventos específicos
Características en VivoHabilita chat, notificaciones, paneles

🚀 Ejemplo Rápido​

📋 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 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 manejadores 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 la frecuencia de eventos de alta frecuencia
  • Agrupa múltiples actualizaciones juntas
  • Debounce las actualizaciones de la interfaz
  • Evita operaciones costosas en los manejadores

💡 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 tokens (igual que 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 manejadores 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étodoDescripciónCaso de Uso
connect()Conectar al servidor WebSocketEstablecer conexión

❓ Preguntas Comunes (FAQ)​

¿Cómo me conecto al servidor WebSocket?​

Usa WS.connect() para establecer una conexión. Espera a que la conexión se abra (escucha el evento onOpen) antes de suscribirte a eventos. La conexión está autenticada usando tu token de aplicación de defineOneEntry().

¿A qué eventos puedo suscribirme?​

Suscríbete a eventos como order.created, order.updated, content.published, payment.completed, user.registered, etc. Los eventos disponibles dependen de tu configuración de OneEntry y de la configuración del módulo de Eventos en el panel de administración.

¿Cómo manejo las caídas de conexión?​

Implementa reconexión automática con retroceso exponencial. Escucha los eventos onClose y onError, 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 la conexión exitosa.

¿Debería usar WebSocket o sondeo para mi aplicación?​

Usa WebSocket para características en tiempo real (chat en vivo, notificaciones, paneles) 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 de 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 desconectarse con retroceso exponencial
  • Desuscríbete en la limpieza - Previene fugas de memoria en SPAs
  • Maneja errores de manera adecuada - Captura errores en los manejadores de eventos
  • Limita eventos de alta frecuencia - Evita abrumar la interfaz con actualizaciones
  • Valida las cargas útiles de los 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

Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/events/introduction

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​