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 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):

// ❌ Malo - Sondeo cada 5 segundos
setInterval(async () => {
  const orders = await Orders.getOrders();
  // Verificar si algo cambió
  // Desperdicia ancho de banda, retrasa actualizaciones, carga del servidor
}, 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:

// ✅ Bueno - Conexión WebSocket en tiempo real
const { WS } = defineOneEntry('https://your-site.oneentry.cloud', {
  token: 'your-app-token'
});

// Suscribirse a eventos
WS.subscribe('order.created', (order) => {
  console.log('¡Nuevo pedido recibido!', order);
  // Notificación instantánea, ¡sin sondeo!
});

WS.subscribe('content.updated', (content) => {
  console.log('¡Contenido actualizado!', content);
  // Actualizar la interfaz de usuario inmediatamente
});

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 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 - Suscribirse 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. El cliente se conecta al servidor WebSocket
   (WS.connect())
   ↓
2. Conexión establecida
   (se activa el evento onOpen)
   ↓
3. El cliente se suscribe a eventos
   (WS.subscribe('event.name', callback))
   ↓
4. El servidor envía eventos cuando ocurren
   (Entrega instantánea)
   ↓
5. El cliente recibe mensajes de eventos
   (Se ejecuta la función de callback)
   ↓
6. La conexión se mantiene abierta
   (No se necesita reconexión)
   ↓
7. El cliente se desconecta cuando termina
   (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 de usuario
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 "Fuera de Stock"

¿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
Basado en EventosSuscribirse a eventos específicos
Características en VivoHabilitar chat, notificaciones, paneles de control

🚀 Ejemplo Rápido​

📋 Lo Que Necesitas Saber​

Gestión de Conexiones WebSocket​

Las conexiones WebSocket deben gestionarse cuidadosamente:

Mejores prácticas:

  • Verificar el estado de la conexión antes de suscribirse
  • Implementar lógica de reconexión
  • Manejar errores de conexión de manera adecuada
  • Desconectar cuando el usuario cierra sesión

Gestión de Suscripciones a Eventos​

Suscribirse a eventos solo después de que la conexión esté establecida

Mejores prácticas:

  • Usar funciones de callback nombradas para facilitar la desuscripción
  • Suscribirse después de que la conexión esté abierta
  • Desuscribirse cuando el componente se desmonte
  • No suscribirse al mismo evento múltiples veces

Desuscripción de Eventos​

Siempre desuscribirse cuando se termine para prevenir fugas de memoria:

Mejores prácticas:

  • Desuscribirse en funciones de limpieza
  • Desconectar WebSocket cuando no sea necesario
  • Prevenir fugas de memoria en SPAs

Estrategia de Reconexión​

Implementar reconexión automática con retroceso exponencial:

Mejores prácticas:

  • Usar retroceso exponencial para la reconexión
  • Limitar el número máximo de intentos de reconexión
  • Reiniciar contadores en conexión exitosa
  • Permitir 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:

  • Validar la estructura de la carga útil del evento
  • Manejar campos faltantes de manera adecuada
  • Verificar tipos de carga útil en TypeScript

Manejo de Errores​

Implementar un manejo de errores integral:

Mejores prácticas:

  • Capturar errores en los controladores de eventos
  • Registrar errores para depuración
  • Mostrar mensajes de error amigables para el usuario
  • No permitir que los errores hagan que la aplicación se bloquee

Optimización del Rendimiento​

Optimizar el rendimiento de WebSocket:

Mejores prácticas:

  • Limitar eventos de alta frecuencia
  • Agrupar múltiples actualizaciones
  • Debounce actualizaciones de la interfaz de usuario
  • Evitar 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​

Desuscribirse cuando se termine para prevenir fugas de memoria

🔒 Seguridad​

Las conexiones WebSocket están autenticadas:

  • Autenticación basada en token (igual que la API REST)
  • Protocolo WebSocket seguro (WSS)
  • No es necesario enviar el token con cada mensaje

Mejores prácticas:

  • Usar WSS (WebSocket seguro) en producción
  • No exponer datos sensibles en los controladores de eventos
  • Validar 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:

  • Reconectar cuando la aplicación vuelva a primer plano
  • Manejar cambios en el estado de la red
  • Considerar 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 Events en el panel de administración.

¿Cómo manejo 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). Reinicia el contador de retraso en 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 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 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. Reconecta 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​

  • Verificar el estado de la conexión - Suscribirse solo después de que la conexión se abra
  • Implementar reconexión - Reconexión automática al desconectarse con retroceso exponencial
  • Desuscribirse en limpieza - Prevenir fugas de memoria en SPAs
  • Manejar errores de manera adecuada - Capturar errores en los controladores de eventos
  • Limitar eventos de alta frecuencia - Evitar abrumar la interfaz de usuario con actualizaciones
  • Validar cargas útiles de eventos - Verificar la estructura de datos antes de procesarlas
  • Usar callbacks nombrados - Más fácil de desuscribirse y depurar
  • Registrar el estado de la conexión - Rastrear 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​