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";
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 Real-time emits one event that allows 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 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 EventData
.
These messages remain accessible in the room's history for up to one year.
const allEvents = await realTime.fetchHistory();
Example of the returned value:
{
"sample.event": [
{
"name": "sample.event",
"data": {
"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 a history of a specific event, you can specify an event name with the fetchHistory
method. The returned object list will be of type EventData
and will contain the last 250 events of the specified event name.
const history = await realTime.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 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 an event, the following arguments can be used:
Name | Type | Description |
---|---|---|
event | string | Required. You can create customized events for your solution or 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. |
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(eventData) {
// do something
}
When subscribing to an event, the received argument will be of type EventData
.
unsubscribe
If you want to stop receiving dispatched events, you can unsubscribe from them using the following code:
realTime.unsubscribe("<EVENT_NAME>");
Types Definitions
EventData
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:
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, is represented as a numerical value. |
RealtimeComponentState
Type: enum
The enumerable represents the Real-time Data Engine's current state. These are the possible values:
STARTED
STOPPED