Saltar al contenido principal

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 - a través de una conexión persistente, de modo que el servidor te envía actualizaciones al instante en lugar de que tú las sondees. Esto habilita características en vivo como notificaciones, chat en vivo y paneles de control en tiempo real.

El único método, connect(), abre la conexión y devuelve un Socket de socket.io. Es síncrono y requiere un usuario autorizado, así que autentica primero.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


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

connect() es síncrono y devuelve un Socket de socket.io (sin await). Adjunta controladores de eventos con socket.on(...):

// connect() requires an authorized user — authenticate first via AuthProvider.
const socket = WS.connect();

socket.on('connect', () => {
  console.log('WebSocket connected');
});

// Listen for an event by its marker (configured in the Events module).
socket.on('my_event', (payload) => {
  console.log('Update received!', payload);
});

✨ 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 - Escucha eventos con socket.on(...)
  • Eficiente - Bajo consumo 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)
Caso de UsoActualizaciones en tiempo realAceptable para actualizaciones no críticas

Ciclo de Vida de la Conexión​

1. Authenticate the user (AuthProvider.auth)
   ↓
2. Open the connection: const socket = WS.connect()
   ↓
3. Wait for the 'connect' event: socket.on('connect', ...)
   ↓
4. Listen for events: socket.on('<event_marker>', callback)
   ↓
5. Server pushes events as they occur
   ↓
6. Disconnect when done: socket.disconnect()

Qué eventos llegan a través de la conexión​

No hay un catálogo fijo de nombres de eventos del 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 típicos de carga útil (ver connect() para ejemplos completos):

Campo de carga útilLlega paraContiene
attributesCada eventoLos propios atributos del evento
productEventos del catálogo (producto)Atributos del producto más title
userEventos de formulario de usuarioCampos del formulario de usuario
orderEventos de pedidosid del pedido y atributos
email / codeFormularios de registro / códigoCampos adicionales del formulario

📋 Lo Que Necesitas Saber​

Se requiere autorización​

connect() requiere un usuario autorizado — llama a AuthProvider.auth(...) antes de conectar. La conexión se autentica con el token de acceso del usuario más tu token de aplicación de defineOneEntry(). Si no hay un usuario autorizado, el SDK registra un error.

connect() es síncrono​

connect() devuelve un Socket de socket.io inmediatamente — no lo await. Espera el evento connect antes de confiar en el socket, luego adjunta controladores con socket.on(...).

Suscríbete después de que se abra la conexión, limpia cuando termines​

Adjunta controladores de eventos después de que se active el evento connect, y deséchalos (socket.off) además de llamar a socket.disconnect() cuando la conexión ya no sea necesaria (por ejemplo, al desmontar el componente o al cerrar sesión del usuario) para prevenir fugas de memoria en SPAs.

Reconexión​

socket.io se reconecta automáticamente por defecto. Para personalizar, escucha los eventos disconnect y connect_error y reconéctate con retroceso exponencial, reiniciando el retraso en una connect exitosa.

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
connect() 🔐Conectar al servidor WebSocketEstablecer conexión

🔐 connect() requiere un usuario autorizado — autentica primero a través de AuthProvider. Después de conectar, adjunta controladores de eventos con socket.on(...).

❓ Preguntas Comunes (FAQ)​

¿Cómo me conecto al servidor WebSocket?​

Usa WS.connect() para abrir una conexión — es síncrono y devuelve un Socket de socket.io. Requiere un usuario autorizado, así que llama a AuthProvider.auth(...) primero. Espera el evento connect antes de confiar en el socket, luego adjunta controladores con socket.on('<event_marker>', callback).

¿A qué eventos puedo suscribirme?​

No hay una lista fija de eventos del SDK. Los eventos se definen 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 las caídas de conexión?​

socket.io se reconecta automáticamente por defecto. Para personalizar, escucha los eventos disconnect y connect_error y reconéctate con retroceso exponencial (por ejemplo, 1s, 2s, 4s, 8s, hasta un máximo), reiniciando el contador de retraso en una connect exitosa.

¿Cómo prevengo fugas de memoria con suscripciones WebSocket?​

Desconecta los controladores de eventos (socket.off) y llama a socket.disconnect() cuando los componentes se desmonten o la conexión ya no sea necesaria. En React, haz esto en la limpieza de useEffect; en Vue, en beforeUnmount.

🎓 Mejores Prácticas​

  • Autentica primero - connect() requiere un usuario autorizado.
  • No esperes a connect() - Es síncrono y devuelve un Socket.
  • Suscríbete después de que se abra la conexión - Adjunta controladores después de que se active el evento connect.
  • Limpia - Desconecta controladores (socket.off) y socket.disconnect() para prevenir fugas de memoria en SPAs.
  • Maneja la reconexión - socket.io se reconecta automáticamente; personaliza con disconnect / connect_error y retroceso si es necesario.
  • Valida las cargas útiles de los eventos - La forma de la carga útil depende de la fuente del evento; verifica los campos antes de usarlos.

🔗 Documentación Relacionada​