SDK Documentation

Complete guide to using the Realtime Gateway SDK

Installation

Include the SDK in your HTML page:

<script src="https://cdn.socket.io/4.8.3/socket.io.min.js"></script>
<script src="https://your-domain.com/gateway-sdk.js"></script>

Connection

Gateway.connect(config)

Connects to the gateway and returns a Promise.

config.app_id required
config.token required
config.url optional 
const gateway = await Gateway.connect({
  url: 'https://your-gateway.com',
  app_id: 'my-app-123',
  token: token,
  domain: window.location.hostname
});

gateway.on('connected', () => {
  console.log('Connected!');
});

Rooms

gateway.join(roomName)

await gateway.join('chat-room-1');

gateway.leave(roomName)

await gateway.leave('chat-room-1');

Events

gateway.on(eventName, callback)

Listen for events broadcast from other clients. Server broadcasts to all except sender.

gateway.on('new-message', (data) => {
  // Only handle messages from other users (not your own)
  if (data.user_id !== currentUserId) {
    console.log('New message:', data.message);
    displayMessage(data);
  }
});

gateway.emit(eventName, roomName, data)

Emit an event to a room. The server broadcasts to all other clients (excluding sender).

gateway.emit('new-message', 'chat-room-1', {
  user_id: 'user-123',
  message: 'Hello!'
});

💡 Best Practice for Chat:

  • Add message optimistically for sender (instant feedback, right side)
  • Server broadcasts to all OTHER clients (excluding sender)
  • Listen for events from others only (check user_id !== current_user_id)
  • This prevents duplicates and provides instant feedback

Typing Indicators

gateway.typing(roomName, data)

gateway.typing('chat-room-1', { user_id: 'user-123' });

Private Messages

gateway.sendPrivateMessage(toUserId, message)

gateway.sendPrivateMessage('user-456', {
  text: 'Hello!',
  timestamp: Date.now()
});

Presence

gateway.ping()

gateway.ping();

Disconnection

gateway.disconnect()

gateway.disconnect();

Complete Example

const gateway = await Gateway.connect({
  url: 'https://your-gateway.com',
  app_id: 'my-app',
  token: token,
  domain: window.location.hostname
});

await gateway.join('chat-room-1');

// Listen for messages from OTHER users only
gateway.on('new-message', (data) => {
  if (data.user_id !== currentUserId) {
    displayMessage(data, false); // false = not sender (left side)
  }
});

// Send message: add optimistically, then emit
function sendMessage(message) {
  const timestamp = Date.now();
  // Add optimistically for sender (right side, instant feedback)
  displayMessage({
    user_id: currentUserId,
    message: message,
    timestamp: timestamp
  }, true); // true = is sender (right side)
  
  // Emit - server broadcasts to all OTHER clients
  gateway.emit('new-message', 'chat-room-1', {
    user_id: currentUserId,
    message: message,
    timestamp: timestamp
  });
}