Real-time Data Engine

Overview

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();

room.addComponent(realtime);

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

Event

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

REALTIME_STATE_CHANGED

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:

Type	Description
RealtimeComponentState	The Real-time Data Engine current state. It can be STARTED or STOPPED.

Methods

fetchHistory

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:

{
    "realtime.host-change": {
        "name": "realtime.host-change",
        "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:

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.
data	unknown	The content of the message can be of any type.
timestamp	number	The timestamp of the message, represented as a numerical value.

Example:

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

publish

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:

Name	Type	Description
event	string	Required. You can create customized events for your solution ou 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.

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:

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

function callbackFunction() {
	// do something
}

unsubscribe

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

realTime.unsubscribe("<EVENT_NAME>");

Types Definitions

RealtimeComponentState

Type: enum

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

• STARTED
• STOPPED