Skip to main content

Introduction

Open a real-time WebSocket connection to receive content, order, and user updates without polling.

More information about the module's user interface https://doc.oneentry.cloud/docs/events/introduction

🎯 What does this module do?​

The WS (WebSocket) module lets you receive real-time notifications - content updates, order changes, user actions - over a persistent connection, so the server pushes updates to you instantly instead of you polling for them. This enables live features like notifications, live chat, and real-time dashboards.

The single method, connect(), opens the connection and returns a socket.io Socket. It is synchronous and requires an authorized user, so authenticate first.

🚀 Quickstart​

Initialize the module from defineOneEntry:


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

connect() is synchronous and returns a socket.io Socket (no await). Attach event handlers with 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);
});

✨ Key Concepts​

What is WebSocket?​

WebSocket is a persistent two-way connection between client and server:

  • Persistent Connection - Stays open, no repeated handshakes
  • Bidirectional - Both client and server can send messages
  • Real-Time - Instant message delivery
  • Event-Based - Listen to events with socket.on(...)
  • Efficient - Low overhead compared to HTTP polling

WebSocket vs HTTP Polling​

FeatureWebSocketHTTP Polling
ConnectionPersistent (stays open)Repeated connections
LatencySub-secondDepends on interval (2-30s)
EfficiencyVery efficientWasteful (many empty responses)
Server LoadLow (events only)High (constant requests)
Use CaseReal-time updatesAcceptable for non-critical updates

Connection Lifecycle​

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

What events arrive over the connection​

There is no fixed catalog of SDK event names. Events fire according to your Events module configuration in the admin panel (the event must have the WebSocket option enabled). You listen for an event by its marker with socket.on('<event_marker>', callback).

The payload depends on the event's source. Typical payload fields (see connect() for full examples):

Payload fieldArrives forContains
attributesEvery eventThe event's own attributes
productCatalog (product) eventsProduct attributes plus title
userUser-form eventsFields from the user form
orderOrder eventsOrder id and attributes
email / codeRegistration / code formsAdditional form fields

📋 What You Need to Know​

Authorization is required​

connect() requires an authorized user — call AuthProvider.auth(...) before connecting. The connection is authenticated with the user's access token plus your app token from defineOneEntry(). If no user is authorized, the SDK logs an error.

connect() is synchronous​

connect() returns a socket.io Socket immediately — do not await it. Wait for the connect event before relying on the socket, then attach handlers with socket.on(...).

Subscribe after the connection opens, clean up when done​

Attach event handlers after the connect event fires, and detach them (socket.off) plus call socket.disconnect() when the connection is no longer needed (e.g. on component unmount or user logout) to prevent memory leaks in SPAs.

Reconnection​

socket.io reconnects automatically by default. To customize, listen for the disconnect and connect_error events and reconnect with exponential backoff, resetting the delay on a successful connect.

📊 Quick Reference Table​

MethodDescriptionUse Case
connect() 🔐Connect to WebSocket serverEstablish connection

🔐 connect() requires an authorized user — authenticate first via AuthProvider. After connecting, attach event handlers with socket.on(...).

❓ Common Questions (FAQ)​

How do I connect to the WebSocket server?​

Use WS.connect() to open a connection — it is synchronous and returns a socket.io Socket. It requires an authorized user, so call AuthProvider.auth(...) first. Wait for the connect event before relying on the socket, then attach handlers with socket.on('<event_marker>', callback).

What events can I subscribe to?​

There is no fixed SDK event list. Events are defined by your Events module configuration in the admin panel (with the WebSocket option enabled), and you listen for an event by its marker with socket.on('<event_marker>', callback). See connect() for payload examples (product, user, order, form).

How do I handle connection drops?​

socket.io reconnects automatically by default. To customize, listen for the disconnect and connect_error events and reconnect with exponential backoff (e.g., 1s, 2s, 4s, 8s, up to a max), resetting the delay counter on a successful connect.

How do I prevent memory leaks with WebSocket subscriptions?​

Detach event handlers (socket.off) and call socket.disconnect() when components unmount or the connection is no longer needed. In React, do this in useEffect cleanup; in Vue, in beforeUnmount.

🎓 Best Practices​

  • Authenticate first - connect() requires an authorized user.
  • Don't await connect() - It's synchronous and returns a Socket.
  • Subscribe after the connection opens - Attach handlers after the connect event fires.
  • Clean up - Detach handlers (socket.off) and socket.disconnect() to prevent memory leaks in SPAs.
  • Handle reconnection - socket.io auto-reconnects; customize with disconnect / connect_error and backoff if needed.
  • Validate event payloads - Payload shape depends on the event source; check fields before using them.

🔗 Related Documentation​