Real-time Data Engine

The Real-time Data Engine is a component that allows you to synchronize data 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 everyone every second, preventing network overload.

Participants can subscribe to real-time events via subscribe, 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.

You can also send events, from a participant to others using the publish, 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. 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.

Before we start

Before utilizing the Mouse Pointers component, it is essential to initialize a room with a defined name and ID for the participant.

How to use

import {
  Realtime,
  useRealtime,
} from "@superviz/react-sdk";
import { useEffect } from "react";

function Room() {
  const { subscribe, unsubscribe, publish } = useRealtime();

  useEffect(() => {
    subscribe("MyEvent", getData);
  }, []);

  const sendData = () => {
    publish("MyEvent", "MyData");
  };

  const getData = (e) => {
    console.log("data", e);
  };

  return (
    <>
      <Realtime />
      <button onClick={sendData}>Send data to everyone in the room</button>
    </>
  );
}

export default Room;

useRealtime Hook

subscribe

Type: (event: string, callback: (data: unknown) => void) => void

Subscribe to an event

function Room() {
  const { subscribe } = useRealtime();

  useEffect(() => {
    subscribe("MyEvent", getData);
  }, []);

  const getData = (e) => {
    console.log("data", e);
  };

  return (
    <Realtime />
  );
}

unsubscribe

Type: (event: string, callback?: (data: unknown) => void) => void

Unsubscribe to an event

function Room() {
  const { unsubscribe } = useRealtime();

  const unsubscribeMe = (e) => {
    unsubscribe("MyEvent");
  };

  return (
    <>
      <Realtime />
      <button onClick={unsubscribeMe}>Unsubscribe to the event</button>
    </>
  );
}

publish

Type: (event: string, data?: unknown) => void

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 room 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.

function Room() {
  const { publish } = useRealtime();

  const sendData = () => {
    publish("MyEvent", "MyData");
  };

  return (
    <>
      <Realtime />
      <button onClick={sendData}>Send data to everyone in the room</button>
    </>
  );
}

fetchHistory

Type: (eventName?: string) => Promise<RealtimeMessage | Record<string, RealtimeMessage>>

Allows you to retrieve data stored in the room. It offers two modes of operation:

• Calling without specifying an event name, you will receive the most recent data of all events published to the room.
• Providing the name of an event, you will receive the most recent data for this event published to the room.

function Room() {
  const { fetchHistory } = useRealtime();

  const fetchMyEventData = (e) => {
    fetchHistory("MyEvent")
      .then((res) => {
        console.log(res.data);
      })
      .catch((err) => {
        console.error("Error:", err);
      });
  };

  const fetchAllData = (e) => {
    fetchHistory()
      .then((res) => {
        console.log(res.data);
      })
      .catch((err) => {
        console.error("Error:", err);
      });
  };

  return (
    <>
      <Realtime />
      <button onClick={fetchMyEventData}>Fetch "MyEvent" data currently stored in the room</button>
      <button onClick={fetchAllData}>Fetch all data currently stored in the room</button>
    </>
  );
}

Type Definitions

RealtimeMessage

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.

RealtimeMessage

Type: object

Realtime message object

Name	Type	Description
name	string	The name of the event
participantId	string	The ID of the participant who sent the event
data	unknown	The data of the event
timestamp	number	The timestamp of the event