Skip to main content

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:

NameTypeDescription
eventstringRequired. You can create customized events for your solution or use one of the names of the events from the SDK.
dataanyUse 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.
warning

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:

room.subscribe('realtime-channel.state-changed', onRealtimeChannelStateChanged);

function onRealtimeChannelStateChanged(state) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
RealtimeChannelStateThe 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:

NameTypeDescription
namestringThe name of the event or which the message history is being retrieved.
participantIdstringParticipant ID responsible for triggering the event. This value can be nullable, meaning that the event wasn't dispatched by a participant.
dataunknownThe content of the message can be of any type.
timestampnumberThe timestamp of the message, is represented as a numerical value.
connectionIdstringThe 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