Skip to main content
EngageFabric provides real-time updates via WebSocket connections, enabling live notifications, leaderboard updates, and multiplayer features.

​
How Real-Time Works

When your application tracks an event via the REST API, the event is published to Redis. The WebSocket server picks up the notification and pushes it to all connected clients in real time.

​
Connecting

Connect to the WebSocket server with authentication: 
import { io } from 'socket.io-client';

const socket = io('wss://api.engagefabric.com', {
  auth: {
    token: 'your-websocket-jwt'
  },
  transports: ['websocket']
});

socket.on('connect', () => {
  console.log('Connected!');
});

socket.on('disconnect', () => {
  console.log('Disconnected');
});

​
Subscriptions

Subscribe to different channels to receive updates:

​
Player Updates

Receive updates when a player’s state changes: 
// Subscribe to player updates
socket.emit('subscribe', {
  channel: 'player',
  playerId: 'player-123'
});

// Listen for events
socket.on('xp_updated', (data) => {
  console.log(`New XP: ${data.xp}`);
});

socket.on('level_up', (data) => {
  console.log(`Reached level ${data.newLevel}!`);
  showCelebration();
});

socket.on('quest_progress', (data) => {
  console.log(`Quest ${data.questId}: ${data.progress}/${data.target}`);
});

socket.on('quest_completed', (data) => {
  console.log(`Quest completed: ${data.questName}`);
  showRewards(data.rewards);
});

​
Leaderboard Updates

Get real-time leaderboard changes: 
socket.emit('subscribe', {
  channel: 'leaderboard',
  leaderboardId: 'weekly-xp'
});

socket.on('leaderboard_updated', (data) => {
  // data.rankings contains updated top players
  updateLeaderboardUI(data.rankings);
});

socket.on('rank_changed', (data) => {
  // Player's rank changed
  console.log(`Your new rank: #${data.rank}`);
});

​
Lobby Updates

For multiplayer features: 
socket.emit('subscribe', {
  channel: 'lobby',
  lobbyId: 'lobby-abc'
});

socket.on('player_joined', (data) => {
  console.log(`${data.playerName} joined the lobby`);
});

socket.on('player_left', (data) => {
  console.log(`${data.playerName} left the lobby`);
});

socket.on('player_ready', (data) => {
  console.log(`${data.playerName} is ready`);
});

socket.on('lobby_started', (data) => {
  console.log('Game starting!');
  startGame(data);
});

​
Chat Messages

Real-time chat: 
socket.emit('subscribe', {
  channel: 'chat',
  channelId: 'lobby-abc-chat'
});

socket.on('chat_message', (data) => {
  displayMessage({
    sender: data.senderName,
    content: data.content,
    timestamp: data.timestamp
  });
});

​
Event Types

​
Player Events

EventDescription
xp_updatedPlayer’s XP changed
level_upPlayer reached a new level
currency_updatedCurrency balance changed
lives_updatedLives count changed
badge_earnedNew badge awarded
quest_progressQuest progress updated
quest_completedQuest finished
quest_unlockedNew quest available

​
Leaderboard Events

EventDescription
leaderboard_updatedRankings changed
rank_changedPlayer’s rank changed
new_high_scoreNew top score recorded

​
Lobby Events

EventDescription
player_joinedPlayer entered lobby
player_leftPlayer exited lobby
player_readyPlayer ready status changed
lobby_startedGame/session started
lobby_closedLobby disbanded

​
Chat Events

EventDescription
chat_messageNew message received
player_typingPlayer is typing
message_deletedMessage was removed

​
Sending Events

Emit events to the server: 
// Send a chat message
socket.emit('chat:send', {
  channelId: 'lobby-abc-chat',
  content: 'Hello everyone!'
});

// Set ready status in lobby
socket.emit('lobby:ready', {
  lobbyId: 'lobby-abc',
  ready: true
});

// Leave a lobby
socket.emit('lobby:leave', {
  lobbyId: 'lobby-abc'
});

​
Connection Management

​
Reconnection

The SDK handles reconnection automatically, but you can customize behavior: 
const socket = io('wss://api.engagefabric.com', {
  auth: { token: 'your-token' },
  reconnection: true,
  reconnectionAttempts: 5,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 5000
});

socket.on('reconnect', (attemptNumber) => {
  console.log(`Reconnected after ${attemptNumber} attempts`);
  // Re-subscribe to channels
  resubscribe();
});

​
Token Refresh

WebSocket tokens expire after 15 minutes. Implement refresh logic: 
socket.on('token_expired', async () => {
  const newToken = await refreshWebSocketToken();
  socket.auth.token = newToken;
  socket.connect();
});

​
Rate Limiting

WebSocket events are rate-limited to prevent abuse:
LimitValue
Events per second10
Subscriptions per connection50
Message size64KB
Exceeding limits triggers a warning event: 
socket.on('rate_limited', (data) => {
  console.warn(`Rate limited: ${data.message}`);
});

​
Best Practices

Unsubscribe when done

Remove subscriptions when leaving screens to reduce bandwidth.

Handle disconnections

Implement reconnection logic and re-subscribe after reconnecting.

Batch updates

Update UI in batches if receiving many events quickly.

Use heartbeats

Monitor connection health with ping/pong events.