Channel API Reference

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. It allows you to subscribe to events, publish messages, and handle channel states.

The Real-time component provides a connect method that allows you to add channels within the same room.

Usage

To use the Channel on your application, create a new instance of the Realtime component and connect to a channel using the connect async method and passing the channel name as an argument.

import { Realtime } from '@superviz/realtime'

const realtime = new Realtime('DEVELOPER_KEY', {
  participant: {
    id: 'PARTICIPANT_ID',
  },
});

const channel = await realtime.connect('YOUR_CHANNEL_NAME');

After initializing it, you can use one of the methods listed below to interact with the channel.

Methods

disconnect()

The disconnect method allows you to disconnect from the channel. When you disconnect from the channel, you will no longer receive events or messages from it.

channel.disconnect();

fetchHistory()

The fetchHistory method is a feature that allows you to retrieve persistent room data stored in our platform. It offers two modes of operation depending on the presence or absence of an event name, you can learn more about it with our Fetching Event History guide.

When fetching history, you can either fetch all events or fetch history for a specific event. The method returns an array of messages that were dispatched to the channel.

// Fetch all events
const allEvents = await channel.fetchHistory();

// Fetch history for a specific event
const eventHistory = await channel.fetchHistory('custom.event');

This method returns an object that stores a list of messages for each topic in a key-value pair format. The key is the event name, and the value is a list of the last 250 events of type RealtimeMessage for that event.

Example of the returned value:

{
  "custom.event": [
    {
      "name": "custom.event",
      "data": {
          "message": "Hello Word"
      },
      "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.

publish()

The publish method allows you to publish messages or events to the channel. Whenever the publish function is called the data within the payload will be disptached across everyone subscribed to the event name provided into the channel.

const payload = { message: 'Hello Word' }; // 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. The name of the event to be dispatched.
data	object	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.

subscribe()

You can subscribe to events dispatched by the publish method using the subscribe method. It receives the event name and a callback function that will be called when the event is dispatched.

The name of the event can be a string literal or one of the values from the RealtimeChannelEvent enum.

Here's how to subscribe to an event with a callback function that will be called when that event is dispatched:

import { RealtimeChannelEvent, RealtimeMessage } from '@superviz/realtime'

function callbackFunction(eventData: RealtimeMessage) {
  // do something
}

// Using string literal
channel.subscribe("EVENT_NAME", callbackFunction);

// Using RealtimeChannelEvent enum
channel.subscribe(RealtimeChannelEvent.REALTIME_CHANNEL_STATE_CHANGED, callbackFunction);

When subscribing to an event, the following arguments can be used:

Name	Type	Description
event	string	Required. The name of the event to be subscribed to.
callback	function	Required. The callback function that will be called when the event is dispatched. When subscribing to an event, the received argument will be of type RealtimeMessage<T>.

unsubscribe()

If you want to stop receiving dispatched events, you can unsubscribe from them using the following code:

The name of the event can be a string literal or one of the values from the RealtimeChannelEvent enum.

// Using string literal
channel.unsubscribe('custom-event');

// Using RealtimeChannelEvent enum
channel.unsubscribe(RealtimeChannelEvent.REALTIME_CHANNEL_STATE_CHANGED);

Events

The channel emits, not only the events you publish, but one event that allows you to monitor and respond to its state changes.

REALTIME_CHANNEL_STATE_CHANGED

The REALTIME_CHANNEL_STATE_CHANGED 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

realTime.subscribe('realtime-channel.state-changed', onChannelStateChange);

function onChannelStateChange(state) {
  // do something
}

TypeScript

import { RealtimeChannelEvent } from '@superviz/realtime'


realTime.subscribe(RealtimeChannelEvent.REALTIME_CHANNEL_STATE_CHANGED, onChannelStateChange);

function onChannelStateChange(state: RealtimeChannelState) {
  // do something
}

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

Type	Description
RealtimeChannelState	The channel component current state. It can be DISCONNECTED, CONNECTED or CONNECTING.

Types

Callback<T>

Callback function type for channel events.

Parameter	Type	Description
data	RealtimeMessage<T> or string	The data received in the callback, either a state or a RealtimeMessage

RealtimeChannelState

Enum representing the state of a realtime channel.

Event	Value	Description
DISCONNECTED	'DISCONNECTED'	The channel is disconnected
CONNECTED	'CONNECTED'	The channel is connected
CONNECTING	'CONNECTING'	The channel is in the process of connecting

RealtimeChannelEvent

Enum of available realtime channel events.

Event	Value	Description
REALTIME_CHANNEL_STATE_CHANGED	'realtime-channel.state-changed'	Used to represent the state of the channel

RealtimeMessage<T>

Represents a realtime message.

Field	Type	Description
name	string	The name of the event or which the message history is being retrieved.
connectionId	string	The connection ID of the connection used to publish the message.
participantId	string or null	Participant ID responsible for triggering the event. This value can be nullable, meaning that the event wasn't dispatched by a participant.
data	T	The payload of the message. The content of the message can be of any type.
timestamp	number	Unix timestamp of when the message was sent.