Channels

Channels are a fundamental concept in real-time communication systems, used to organize and categorize messages based on specific topics or themes. They implement the Publish-Subscribe (Pub/Sub) architectural pattern, which allows for efficient and scalable communication between multiple parties.

In the Pub/Sub model:

• Publishers can send messages to a channel without knowing who will receive them.
• Subscribers can receive messages from a channel without knowing who sent them.
• Any number of publishers can publish to a channel.
• Any number of subscribers can subscribe to a channel.

This decoupling between publishers and subscribers provides flexibility and scalability in real-time applications, allowing for easy addition or removal of participants without affecting the overall system.

Entering in a channel

A Channel object represents a single communication channel, identified by a unique unicode string name. To create a new channel or retrieve an existing one from the Channels collection, you use the connect() method. This method returns a Channel object, which serves as your interface for interacting with that specific channel.

Here's a basic example of how to connect to a channel:

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

 const channel = await realtime.connect('channel-name')

Subscribing to events

Once you have connected to a channel, you can subscribe to specific events within that channel. Subscribing allows you to listen for and react to particular types of messages or events that are published to the channel.

To subscribe to an event, you use the subscribe() method on the Channel object. This method takes two parameters:

1. The name of the event you want to subscribe to (as a string)
2. A callback function that will be executed whenever the specified event occurs

Here's how you can subscribe to an event:

 const channel = await realtime.connect('channel-name')
 channel.subscribe('event-name', (data) => {
   // do something
 })

Unsubscribing from events

If you no longer want to receive updates for a specific event, you can unsubscribe from it. This is particularly useful for managing resources and preventing memory leaks in your application.

To unsubscribe from an event, you use the unsubscribe() method on the Channel object. This method can be used in two ways:

1. To unsubscribe a specific callback from an event:

   • Pass the event name and the callback function as parameters.

2. To unsubscribe all callbacks from an event:

   • Pass only the event name as a parameter.

Here's how you can unsubscribe from an event:

 const channel = await realtime.connect('channel-name')
 
 // Unsubscribe a specific callback
 const callback = (data) => {
   // do something
 }
 channel.subscribe('event-name', callback)
 channel.unsubscribe('event-name', callback)

 // Unsubscribe all callbacks for an event
 channel.unsubscribe('event-name')

After unsubscribing, you will no longer receive updates for the specified event on that channel. If you unsubscribed a specific callback, other callbacks for the same event will continue to receive updates. If you unsubscribed all callbacks, no updates will be received for that event until new subscriptions are made

Publishing events

To send data to other participants in the channel, you can use the publish() method. This method allows you to broadcast events and data to all subscribers of a specific event type in the channel.

The publish() method takes two parameters:

1. The event name
2. The data you want to send

Here's how you can publish an event:

 const channel = await realtime.connect('channel-name')
 
 // Publish an event
 channel.publish('event-name', { message: 'Hello, channel!' })

When you publish an event, all participants who have subscribed to that event type in the channel will receive the data. This allows for real-time communication and data sharing between participants in your application.

warning

The maximum message size is 120KB per message, and any single message larger than this will be ignored. Additionally, the maximum throughput is limited to 1000 messages per second; if more than 1,000 messages are sent within one second, the excess messages will be ignored.

Fetching Event History

The fetchHistory() method allows you to retrieve persistent room data stored in SuperViz's Real-Time Engine. This feature is useful for accessing historical events and data within a channel.

Fetching All Events

To retrieve a comprehensive history of all events in the channel, you can call fetchHistory() without specifying an event name:

const allEvents = await channel.fetchHistory();

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:

{
  "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 in the channel.

info

These messages remain accessible in the room's history for up to one year.

Fetching History for a Specific Event

To retrieve the history of a particular event, you can provide the event name as an argument to fetchHistory():

const eventHistory = await channel.fetchHistory('sample.event');

This will return an array of RealtimeMessage objects for the specified event, containing up to the last 250 occurrences of that event.

The RealtimeMessage object has the following structure:

interface RealtimeMessage {
  name: string;
  data: any;
  participantId: string;
  timestamp: number;
  connectionId: string;
}

By using fetchHistory(), you can easily access and utilize historical data in your application, enabling features like message history, state recovery, or analysis of past events.