Real-Time Features

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

Event	Description
`xp_updated`	Player’s XP changed
`level_up`	Player reached a new level
`currency_updated`	Currency balance changed
`lives_updated`	Lives count changed
`badge_earned`	New badge awarded
`quest_progress`	Quest progress updated
`quest_completed`	Quest finished
`quest_unlocked`	New quest available

Leaderboard Events

Event	Description
`leaderboard_updated`	Rankings changed
`rank_changed`	Player’s rank changed
`new_high_score`	New top score recorded

Lobby Events

Event	Description
`player_joined`	Player entered lobby
`player_left`	Player exited lobby
`player_ready`	Player ready status changed
`lobby_started`	Game/session started
`lobby_closed`	Lobby disbanded

Chat Events

Event	Description
`chat_message`	New message received
`player_typing`	Player is typing
`message_deleted`	Message 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:

Limit	Value
Events per second	10
Subscriptions per connection	50
Message size	64KB

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.

Getting Started

Guides

Core Concepts

API Reference

Endpoints

SDKs

Resources

How Real-Time Works

Connecting

Subscriptions

Player Updates

Leaderboard Updates

Lobby Updates

Chat Messages

Event Types

Player Events

Leaderboard Events

Lobby Events

Chat Events

Sending Events

Connection Management

Reconnection

Token Refresh

Rate Limiting

Best Practices

Unsubscribe when done

Handle disconnections

Batch updates

Use heartbeats

​How Real-Time Works

​Connecting

​Subscriptions

​Player Updates

​Leaderboard Updates

​Lobby Updates

​Chat Messages

​Event Types

​Player Events

​Leaderboard Events

​Lobby Events

​Chat Events

​Sending Events

​Connection Management

​Reconnection

​Token Refresh

​Rate Limiting

​Best Practices

Unsubscribe when done

Handle disconnections

Batch updates

Use heartbeats

How Real-Time Works

Connecting

Subscriptions

Player Updates

Leaderboard Updates

Lobby Updates

Chat Messages

Event Types

Player Events

Leaderboard Events

Lobby Events

Chat Events

Sending Events

Connection Management

Reconnection

Token Refresh

Rate Limiting

Best Practices