Socket.IO Client Integration Guide

Overview

This guide provides a comprehensive set of instructions for integrating a client application with the Hubtel Realtime Socket.IO server. It includes how to connect to the server, handle various events, emit messages, and manage connection errors.

Prerequisites

To integrate your client application with the Hubtel Realtime Socket.IO server, you need to have the following:

Socket.IO Client Library: For web applications, use socket.io-client. For other platform, use the appropriate Socket.IO client library.

Install the library using npm:

npm install socket.io-client

Server URL: Know the URL for the Socket.IO server

CORS Configuration: CORS Configuration: Ensure the server allows connections from your client’s domain. Contact the product SRE team for assistance with CORS configuration.

Connecting to the Server

Basic Connection

Use socket.io-client to establish a connection to the Socket.IO server. Replace 'https://your-server-address:port' with the actual server URL.

import io from 'socket.io-client';

// Connect to the server
const socket = io('https://hubtel-palceholder-socket.com', {
  transports: ['websocket', 'polling'], // Specify the transport methods
});

Handling Connection Events

After connecting to the server, you can handle various connection related events such as connect, disconnect, and connection errors.

// Event when connected
socket.on('connect', () => {
  console.log('Successfully connected to the server');
});

// Event when disconnected
socket.on('disconnect', () => {
  console.log('Disconnected from the server');
});

// Event when there’s a connection error
socket.on('connect_error', (err) => {
  console.error('Connection Error:', err);
});

Channel

A channel is a communication pathway in the Socket.io server that allows for real-time data exchange between the client and server, ensuring all connected clients receive broadcasted messages.

See it as a public communication line where everyone can listen in, ensuring that all participants have access to general updates and information, promoting broad communication.

All messages sent and received from a channel are broadcasted to all connected clients, formatted as objects with a specific structure.

How To Join A Channel

To join a channel, the client emits a join-channel event to the server. The server then adds the client to the channel.

socket.emit("join-channel", 
{ data: 
  {
      message: "",
      roomId: null,
      roomChannel: "some-channel-id",
    },
    time: "2021-09-01T12:00:00.000Z",
    clientId: socket.id,
    source: {
      platform: "web",
      appName: "Sample App Name",
      appVersion: "1.0.0",
      clientId: socket.id, 
      userName: "John Doe", 
      channel: "some-channel-id",
    }});

The above code adds the user to the channel with the ID some-channel-id. A typical use case is when two or more users need to communicate with each other in a group chat or discussion forum. In such case, the users join the same channel: some-channel-id to receive messages from other participants.

Send Message to a channel

To send a message to a channel, the client emits to the channel Id with the message payload. The server then broadcasts the message to all connected clients in the channel.

const sendMessage = () => {
    const data =
    { data: 
    {
      message: "This is a message",
      roomId: null,
      roomChannel: "channelId",
    },
    time: "2021-09-01T12:00:00.000Z",
    clientId: socket.id,
    source: {
      platform: "web",
      appName: "Sample App Name",
      appVersion: "1.0.0",
      clientId: socket.id, 
      userName: "John Doe", 
      channel: "channelId",
    }}
    socket.emit("channelId", data );
  }

The above code sends a message to the channel with the ID channelId. The message is broadcasted to all connected clients in the channel.

Leave A Channel

When a client is no longer interested in receiving messages from a channel, it can leave the channel by emitting a leave-channel event to the server. The server then removes the client from the channel.

socket.emit("leave-channel", { data: {
      message: "",
      roomId: null,
      roomChannel: "channelId",
    },
    time: "2021-09-01T12:00:00.000Z",
    clientId: socket.id,
    source: {
      platform: "web",
      appName: "Sample App Name",
      appVersion: "1.0.0",
      clientId: socket.id, 
      userName: "John Doe", 
      channel: "channelId",
    }}
    );

Other Sever Events for Channels

The server emits certain events to the clients in a channel. The client can listen to these events using the on method.

Event Name	Description
online-users	Sent by the server to provide data on the number of online users across channels.
join-channel	Sent by the server when a new user join a specific channel.
leave-channel	Sent by the server when a new user leave a specific channel.

See example below:

socket.on('online-users', (data: Message) => {
  console.log('Online Users:', data);
});

Room

A room is a sub-division within a channel that allows grouping of clients. It enables targeted message delivery to specific clients, facilitating private and efficient communication within the broader channel.

A room within that channel is like a private discussion group where only selected participants can join, enabling focused, private conversations and ensuring that relevant information is shared only with those who need it.

Join A Room

To join a room, the client emits a join-room event to the server. A client can join a room in a channel.

socket.emit("join-room", { data:{
      message: "",
      roomId: "roomId", // roomId is required to join a room. If the room does not exist, it will be created.
      roomChannel: "channelId",
    },
    time: "2021-09-01T12:00:00.000Z",
    clientId: socket.id,
    source: {
      platform: "web",
      appName: "Sample App Name",
      appVersion: "1.0.0",
      clientId: socket.id, 
      userName: "John Doe", 
      channel: "channelId",
    }}
    );

Send Message to a Room

To send a message to a room, the client emits a notify-room event to the server. The server then broadcasts the message to all connected clients in the room.

const sendMessage = () => { data: {
    const data = {
      message: "This message is going to all clients in roomId",
      roomId: "roomId",
      roomChannel: "channelId",
    },
    time: "2021-09-01T12:00:00.000Z",
    clientId: socket.id,
    source: {
      platform: "web",
      appName: "Sample App Name",
      appVersion: "1.0.0",
      clientId: socket.id, 
      userName: "John Doe", 
      channel: "channelId",
    }},
    socket.emit("notify-room", data ); // If you
  }

Leave A Room

When a client is no longer interested in receiving messages from a room, it can leave the room by emitting a leave-room event to the server. The server then removes the client from the room.

socket.emit("leave-room", { data: {
      message: "",
      roomId: "roomId",
      roomChannel: "channelId",
    },
    time: "2021-09-01T12:00:00.000Z",
    clientId: socket.id,
    source: {
      platform: "web",
      appName: "Sample App Name",
      appVersion: "1.0.0",
      clientId: socket.id, 
      userName: "John Doe", 
      channel: "channelId",
    }});

Other Sever Events for Rooms

The server emits certain events to the clients in a particular which be useful.

Event Name	Description
room-online-users	Sent by the server to provide data on the number of online users in a specific room. The event is emitted whe a new user joins the room
join-room	Emitted when a new user join a specific room.
leave-room	Emitted when a new user leave a specific room.

Request Payload

The request payload is the data structure that the client sends to the server when emitting an event. The payload contains the message, room ID, room channel, time, client ID, and source information.

Field	Description
data	An object containing information about the message
data.message	The message to be sent to the server. If the event does not require a message, pass an empty string
data.roomId	The ID of the room to which the message belongs. Pass null for channel communication
data.roomChannel	The ID of the channel to which the room belongs.
time	The timestamp of the message.
clientId	The ID of the client sending the message.
source	Information about the source of the message, including platform and app details.
source.platform	The platform from which the message is sent (e.g., web, mobile).
source.appName	The name of the application sending the message.
source.appVersion	The version of the application sending the message.
source.clientId	The ID of the client sending the message.
source.userName	The name of the user sending the message.
source.channel	The id of the channel the message is sent from