Skip to main content
Version: Latest

Real-time Data Engine


The Real-time Data Engine is a component of the SDK that allows you to synchronize states between participants in a room. This enables various functionalities such as real-time data sharing, and event-driven communication for seamless collaborative experiences.


How it works

The Real-time Data Engine collects participant-triggered events and sends them to others every second, preventing network overload.

Participants can subscribe to real-time events via the subscribe method, triggering a callback function whenever an event is received.

After subscribing to real-time events using the subscribe method, if you wish to stop receiving dispatched events, you can achieve this by utilizing the unsubscribe method.

You can also 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.

How SuperViz SDK uses it

SuperViz SDK uses the Real-time Data Engine to ensure its components have participant data synchronized between them. For a complete list of events dispatched by the SDK, regardless of the component you are using, please refer to our event documentation.

However, please note that events can be in a component context, and not always available for the room. They must be subscribed to through the respective component, such as the Video Conference. For those events, please refer to the documentation of the specific component for more details on how to subscribe and handle them.

Here are some examples of events related to rooms and components:

  • The room-related events, like the ParticipantEvent.LEFT that occurs when a participant leaves the room.
  • Components-related events, like the MeetingEvent.MEETING_PARTICIPANT_AMOUNT_UPDATE that occur when the number of participants in the meeting changes.

Before we start

Before utilizing the Real-time Data Engine component, it is essential to initialize a room with a defined name and ID for the participant and for the group.

How to use

To use the Real-time Data Engine on your application, use the following code:

import { Realtime } from "@superviz/sdk/lib/components";

const realtime = new Realtime();


After initializing it, you can use one of the methods listed below to interact with the Real-time Data Engine.


The Realtime emits one event that allow you to monitor and respond to its changes within the room in real-time.


The REALTIME_STATE_CHANGED is dispatched when there is a change under the current state of the Real-time Data Engine.

Here is an implementation on how to catch the dispatched event:

room.subscribe(RealtimeComponentEvent.REALTIME_STATE_CHANGED, onRealTimeEngineStateChanged);

function onRealTimeEngineStateChanged(state) {
// do something

On the callback function you will receive the following argument:

RealtimeComponentStateThe Real-time Data Engine current state. It can be STARTED or STOPPED.



The fetchHistory method is a feature that allows you to retrieve persistent room data stored in the Real-time Data 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 most recent update for this event.

Without specifying an event name

This method stores the most recent message for each topic in a convenient key-value pair list, with the key being the event name, and the value being its content. These messages remain accessible in the room's history for up to one year.

const allEvents = await realTime.fetchHistory();

Example of the returned value:

"": {
"name": "",
"data": {
"id": "<USER_ID>",
"name": "<USER_NAME>",
"type": "host",
"isHost": false,
"color": "#FFEF33"
"participantId": "<USER_ID>",
"timestamp": 1696845547544

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 the latest update for a specific event, you can specify an event name with the fetchHistory method. The returned object includes information such as the event name, participant ID responsible for triggering the event, the payload, and the timestamp for precise data tracking

const history = await realTime.fetchHistory("<EVENT_NAME>");

The return value of this method is an object containing the following properties:

namestringThe name of the event or which the message history is being retrieved.
participantIdstringParticipant ID responsible for triggering the event.
dataunknownThe content of the message can be of any type.
timestampnumberThe timestamp of the message, represented as a numerical value.


"name": "<EVENT_NAME>",
"data": {},
"participantId": "<USER_ID>",
"timestamp": 1696845547544


The publish method allows you to publish messages or events to the Real-time Data Engine.

Whenever a user calls the publish function, the data within that property is synchronized with all meeting participants. The most recent message for that property is automatically saved in a history log, allowing participants to retrieve it at any point during the meeting.

const payload = PAYLOAD; // Create your own payload here

realTime.publish("<EVENT_NAME>", payload);

When publishing and event, the following arguments can be used:

eventstringRequired. You can create customized events for your solution ou 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.

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.


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:

realTime.subscribe("<EVENT_NAME>", callbackFunction);

function callbackFunction() {
// do something


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


Types Definitions


Type: enum

The enumarable represents the Real-time Data Engine current state. This is the possible values: