Channels
A channel can be used to dispatch different types of messages or events in your application. It allows you to create a dedicated communication path for specific types of messages, ensuring that only the intended participants receive them.
The Real-time Data Engine component provides a connect
method that allows you to add channels within the same room.
How it works
The channel collects participant-triggered events and sends them to every participant subscribed to the channel in real time.
Participants can subscribe to real-time events via the subscribe
method, triggering a callback function whenever an event is received.
After subscribing to channel events using the subscribe
method, if you wish to stop receiving dispatched events, you can achieve this by utilizing the unsubscribe
method.
You can send events, from a participant to others using the publish
method, specifying an event name and payload. The name identifies the event, while the payload carries data for recipients. Although the payload can be of any data type, it's recommended to use a simple object or a string.
You can retrieve saved data in the engine at any time using fetchHistory
method. This method offers two distinct modes of operation based on your needs: whether you need a complete historical record or just the latest information for a particular event.
Before we start
Before utilizing any Channel, it is essential to initialize a room with a defined name and ID for the participant and the group, and also to have initialized the Realtime
component to enable a channel connection. The Realtime
component should be added to the room.
How to Use
To use the Channel on your application, create a new instance of the Realtime
component and connect to a channel using the connect
method and passing the channel name as an argument. You will need to make sure that the Real-time is ready before adding the channel to it.
import { Realtime } from "@superviz/sdk";
const realtime = new Realtime();
room.addComponent(realtime);
realtime.subscribe(RealtimeComponentEvent.REALTIME_STATE_CHANGED, (state) => {
if (state === RealtimeComponentState.STARTED) {
const channel = realtime.connect('YOUR_CHANNEL_NAME');
}
});
After initializing it, you can use one of the methods listed below to interact with the Real-time Data Engine.
Methods
fetchHistory
The fetchHistory
method is a feature that allows you to retrieve persistent room data stored in our engine. It offers two modes of operation depending on the presence or absence of an event name, when:
- Calling without specifying an event name, you will receive a comprehensive history of all events.
- Providing the name of an event, you will receive the history of this particular event.
Without specifying an event name
This method enables you to receive a list of events that have been dispatched in the room. It will return an object that stores a list of messages for each topic in a convenient key-value pair list, with the key being the event name, and the value being a list of the last 250 events called of the type RealtimeMessage
.
These messages remain accessible in the room's history for up to one year.
const allEvents = await channel.fetchHistory();
Example of the returned value:
{
"sample.event": [
{
"name": "sample.event",
"data": {
"color": "#FFEF33"
},
"participantId": "PARTICIPANT_NAME",
"timestamp": 1696845547544,
"connectionId": "CONNECTION_ID"
}
]
}
If an event name is not found in the key-value pair list, it indicates that the event has not yet been dispatched.
Providing an event name
When you need a history of a specific event, you can specify an event name with the fetchHistory
method. The returned object list will be of type RealtimeMessage
and will contain the last 250 events of the specified event name.
const history = await channel.fetchHistory("EVENT_NAME");
Example:
[
{
"name": "EVENT_NAME",
"data": {},
"participantId": "USER_ID",
"timestamp": 1696845547544
}
]
publish
The publish
method allows you to publish messages or events to the channel.
Whenever a participant calls the publish
function, the data within that property is synchronized with all participants in the room.
const payload = PAYLOAD; // Create your own payload here
channel.publish("EVENT_NAME", payload);
When publishing an event, the following arguments can be used:
Name | Type | Description |
---|---|---|
event | string | Required. You can create customized events for your solution or use one of the names of the events from the SDK. |
data | any | Use this field to pass any data type (number , boolean , string , or a simple object or array ) as payload on the event dispatch. Note: The maximum message size is 10kb, and any message bigger than that will be ignored. |
The maximum message size is 10 KB per message. Any single message larger than 10 KB will be ignored. The total maximum throughput of queried messages is 64 KB per second. Queries of messages that exceed a combined size of 64 KB in one second, be will be processed in the following second.
subscribe
You can subscribe to the SDK predefined or your custom events dispatched by the publish
method.
Here's how to subscribe to an event with a callback function that will be called when that event is dispatched:
channel.subscribe("EVENT_NAME", callbackFunction);
function callbackFunction(eventData) {
// do something
}
When subscribing to an event, the received argument will be of type RealtimeMessage
.
unsubscribe
If you want to stop receiving dispatched events, you can unsubscribe from them using the following code:
channel.unsubscribe("EVENT_NAME");
disconnect
The disconnect
method allows you to disconnect from the channel, stopping the reception of events and messages.
channel.disconnect();
Event
The Real-time emits one event that allows you to monitor and respond to its changes within the room in real time.
RealtimeChannelEvent
The RealtimeChannelEvent
is dispatched when there is a change under the current state of the channel.
Here is an implementation on how to catch the dispatched event:
- JavaScript
- TypeScript
room.subscribe('realtime-channel.state-changed', onRealtimeChannelStateChanged);
function onRealtimeChannelStateChanged(state) {
// do something
}
room.subscribe(RealtimeChannelEvent.REALTIME_CHANNEL_STATE_CHANGED, onRealtimeChannelStateChanged);
function onRealtimeChannelStateChanged(state: RealtimeChannelState) {
// do something
}
On the callback function, you will receive the following argument:
Type | Description |
---|---|
RealtimeChannelState | The Channel current state. It can be DISCONNECTED , CONNECTED , or CONNECTING . |
Types Definitions
RealtimeMessage
Type: object
This is the representation of the data structure of the event dispatched by the Real-time Data Engine. It contains the following properties:
Name | Type | Description |
---|---|---|
name | string | The name of the event or which the message history is being retrieved. |
participantId | string | Participant ID responsible for triggering the event. This value can be nullable, meaning that the event wasn't dispatched by a participant. |
data | unknown | The content of the message can be of any type. |
timestamp | number | The timestamp of the message, is represented as a numerical value. |
connectionId | string | The connection ID of the connection used to publish the message. This value can be nullable, meaning that the event wasn't dispatched by a participant. |
RealtimeChannelState
Type: enum
The enumerable represents the channels's current state. These are the possible values:
DISCONNECTED
CONNECTED
CONNECTING