Room API Reference

The SuperVizRoom component is the core element enabling real-time, multi-user interactions within your application. By integrating a room, you create a virtual space where users, or "participants," can join to collaborate in real-time.

How to use

To initialize the Room component, you can follow our quickstart guide.

Usage

To add a room to your application, use the following code:

import SuperVizRoom from "@superviz/sdk";

async function initializeSuperVizRoom() {
  const room = await SuperVizRoom(DEVELOPER_KEY, {
    roomId: "ROOM_ID",
    group: {
      id: "GROUP_ID",
      name: "GROUP_NAME",
    },
    participant: {
      id: "USER_ID",
      name: "USER_NAME",
    },
  });

  return room;
}

When initializing a room you must pass parameters for it to work properly. See below the available parameters:

Name	Type	Description
`roomId`	`string`	Required. This is a unique ID that you can create on your end. Using the same ID you will be able to enter the same room. Minimum length of 2 characters and maximum of 64. Accepted pattern: `[-_&@+=,()\{\}\\[\\]\/«».:\|'"#a-zA-Z0-9À-ÿ\s]*`
`group`	`Group`	Required. You can organize your participants into groups. Usually, a group is a company or organization.
`participant`	`Participant`	Required. An object describing the user that will participate in the room.
`debug`	`boolean`	Enable SDK logs in the browser console. Default value: `false`

After you’ve initialized the SDK, you have the flexibility to implement our SDK methods for adding or removing any of our components, while also taking advantage of event-handling capabilities through the Real-time Data Engine.

tip

Remember to factor in the Monthly Active User (MAU) count during development and production. MAUs are calculated based on each new participant.id entry when using Presence and Contextual Comments. For more details, please visit our pricing page.

Methods

Once you've initialized, you'll have access to methods that allow you to interact with the SDK and perform various tasks. Below are the methods available.

`addComponent`

Once you've initialized the room, you may want to add components such as Mouse Pointers or Video Huddle. The addComponent method facilitates this process. Here's an example of how to use it:

const room = await SuperVizRoom(DEVELOPER_KEY, {});

const videoConference = new VideoConference();

room.addComponent(videoConference);

`removeComponent`

If you wish to remove previously added components, you can achieve this with the removeComponent method. Here's how to use it:

room.removeComponent(videoConference);

`destroy`

If you wish to unload the room and its components, you can achieve this with the destroy method. Here's how to use it:

room.destroy();

Events

`JOINED`

The JOINED is dispatched when a participant enters the room.

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

JavaScript
TypeScript

room.subscribe('participant.joined', onParticipantJoined);

function onParticipantJoined(participant) {
// do something
}

room.subscribe(ParticipantEvent.JOINED, onParticipantJoined);

function onParticipantJoined(participant) {
	// do something
}

On the callback function, you will receive the following argument:

Type	Description
`Participant`	The participant details that had joined the room triggered the event.

Example:

{
    "id": "USER_ID",
    "color": "#878291",
    "type": "host",
    "name": "USER_NAME",
    "isHost": true
}

`LEFT`

The LEFT is dispatched when a participant leaves the meeting room.

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

JavaScript
TypeScript

room.subscribe('participant.left', onParticipantLeft);

function onParticipantLeft(participant) {
// do something
}

room.subscribe(ParticipantEvent.LEFT, onParticipantLeft);

function onParticipantLeft(participant) {
	// do something
}

On the callback function, you will receive the following argument:

Type	Description
`Participant`	The participant details that had left the room triggered the event.

Example:

{
    "id": "USER_ID",
    "color": "#878291",
    "type": "host",
    "name": "USER_NAME",
    "isHost": true
}

`LOCAL_JOINED`

This event will be dispatched when the local participant enters the room.

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

JavaScript
TypeScript

room.subscribe('participant.local-joined', onParticipantLocalJoin);

function onParticipantLocalJoin(participant) {
// do something
}

room.subscribe(ParticipantEvent.LOCAL_JOINED, onParticipantLocalJoin);

function onParticipantLocalJoin(participant) {
	// do something
}

On the callback function, you will receive the following argument:

Type	Description
`Participant`	Participant that triggered the event by entering the room.

Example:

{
    "id": "USER_ID",
    "color": "#878291",
    "type": "host",
    "name": "USER_NAME",
    "isHost": true
}

`LOCAL_LEFT`

This event will be dispatched when the local participant leaves the room.

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

JavaScript
TypeScript

room.subscribe('participant.local-left', onParticipantLocalLeft);

function onParticipantLocalLeft(participant) {
// do something
}

room.subscribe(ParticipantEvent.LOCAL_LEFT, onParticipantLocalLeft);

function onParticipantLocalLeft(participant) {
	// do something
}

On the callback function, you will receive the following argument:

Type	Description
`Participant`	Participant that triggered the event by leaving the room.

Example:

{
    "id": "USER_ID",
    "color": "#878291",
    "type": "host",
    "name": "USER_NAME",
    "isHost": true
}

`LOCAL_UPDATED`

The LOCAL_UPDATED will be triggered when there is any change to the local participant.

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

JavaScript
TypeScript

room.subscribe('participant.updated', onParticipantLocalUpdate);

function onParticipantLocalUpdate(participant) {
// do something
}

room.subscribe(ParticipantEvent.LOCAL_UPDATED, onParticipantLocalUpdate);

function onParticipantLocalUpdate(participant) {
	// do something
}

On the callback function, you will receive the following argument:

Type	Description
`Participant`	Participant that was updated.

Example:

{
    "id": "USER_ID",
    "color": "#878291",
    "type": "host",
    "name": "USER_NAME",
    "isHost": true
}

`LIST_UPDATED`

Use the LIST_UPDATEDto be notified of the current participants list, whenever there is a change on the list of participants in the room.

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

JavaScript
TypeScript

room.subscribe('participant.list-updated', onListUpdate);

function onListUpdate(participants) {
// do something
}

room.subscribe(ParticipantEvent.LIST_UPDATED, onListUpdate);

function onListUpdate(participants) {
	// do something
}

On the callback function, you will receive the following argument:

Type	Description
`Participant[]`	Actual list of participants in the room.

Example:

[
  {
    id: "USER_ID",
    color: "#878291",
    type: "host",
    name: "USER_NAME",
    isHost: true,
  },
];

`SAME_ACCOUNT_ERROR`

The SAME_ACCOUNT_ERROR event is triggered when a participant tries to enter the room with the same ID that is already in the room. Here is an implementation on how to catch the dispatched event:

JavaScript
TypeScript

room.subscribe('participant.same-account-error', onSameAccountError);

function onSameAccountError() {
// do something
}

room.subscribe(ParticipantEvent.SAME_ACCOUNT_ERROR, onSameAccountError);

function onSameAccountError() {
	// do something
}

`MOUNT`

The MOUNT event is triggered when a component fully is mounted in the room. Here is an implementation on how to catch the dispatched event:

JavaScript
TypeScript

room.subscribe('mount', onComponentMouted);

function onComponentMouted() {
// do something
}

room.subscribe(ComponentLifeCycle.MOUNT, onComponentMouted);

function onComponentMouted() {
	// do something
}

`UNMOUNT`

The UNMOUNT event is triggered when a component fully is destroyed in the room. Here is an implementation on how to catch the dispatched event:

JavaScript
TypeScript

room.subscribe('unmount', onComponentUnmouted);

function onComponentUnmouted() {
// do something
}

room.subscribe(ComponentLifeCycle.UNMOUNT, onComponentUnmouted);

function onComponentUnmouted() {
	// do something
}

Type Definitions

`Avatar`

Type: object

Avatars represent participants within a room. In typical scenarios, they appear as profile images when used with Who-is-Online and Contextual Comments.

In 3D spaces (e.g., Matterport, Autodesk viewer or ThreeJs), avatars can take the form of 3D digital representations.

Name	Type	Description
`imageUrl`	`string`	Required. Path to the thumbnail image of the 3D model. Supported formats: `.png` and `.jpg`.
`model3DUrl`	`string`	Path to a 3D model. Only applicable when using Presence3D components Supported formats: `.glb` and `.gltf`.

Example:

avatar: {
	imageUrl: "https://<PATH>",
	model3DUrl: "https://<PATH>",
}

tip

If you don’t have an avatar you can use the default avatars that we provide in the meeting setup, or you can create them on our Ready Player Me, as our code is optimized to work with their 3D models.

`ComponentNames`

Type: enum

List of possible components that a participant can be added to. This is a read-only property, to add a participant into a component, you should use the addComponent method of the room. The options are:

Name	Value	Component
`ComponentNames.WHO_IS_ONLINE`	`whoIsOnline`	Who-is-Online
`ComponentNames.VIDEO_CONFERENCE`	`videoConference`	Video Huddle
`ComponentNames.COMMENTS`	`comments`	Contextual Comments
`ComponentNames.PRESENCE`	`presence`	Indicates that any presence component is active (Mouse-Pointers or Who-is-Online).
`ComponentNames.PRESENCE_AUTODESK`	`presence3dAutodesk`	Presence 3D Autodesk
`ComponentNames.PRESENCE_MATTERPORT`	`presence3dMatterport`	Presence 3D Matterport
`ComponentNames.PRESENCE_THREEJS`	`presence3dThreejs`	Presence 3D Three.js

`Group`

Type: object

You can organize your participants into groups, typically representing companies or organizations.

Name	Type	Description
`id`	`string`	A unique ID that identifies the group. Usually, this ID matches your internal ID of a specific company or organization.
`name`	`string`	The name of the group.

Example:

group: {
  id: "GROUP_ID",
  name: "GROUP_NAME",
}

`Participant`

Type: object

An object describing the participant information, like name and avatar.

Name	Type	Description
`id`	`string`	Required. Identifier of the participant who is entering the room. Usually, this ID matches the internal ID of your users. Minimum length of 2 characters and maximum of 64. Accepted pattern: `[-_&@+=,()\{\}\\[\\]\/«».:\|'"#a-zA-Z0-9À-ÿ\s]*`
`avatar`	`Avatar`	Participant avatar information.
`avatarConfig`	`unknown`	Read-only. Avatar configuration, The same configurations passed when creating an Autodesk Viewer, Matterport, or Three.js avatar on Presence 3D.
`color`	`string`	Read-only. Unique color for the participant in the room, is used to identify the participant in presence components like Who-is-Online, Mouse Pointers, and avatar/laser in 3D space.
`activeComponents`	`ComponentNames[]`	Read-only. List of active components that the participant has entered.
`isHost`	`boolean`	Read-only. Indicates if the participant is the current host of the room.
`name`	`string`	Required. The name of the participant who will enter the room.
`type`	`ParticipantType`	Read-only. Participant permission in the room. Options are host, guest, and audience.

Example:

participant: {
  id: "USER_ID",
  name: "USER_ID",
  type: "host",
  color: "#878291",
  isHost: false,
  activeComponents: ["comments", "presence"],
  avatar: {
    imageUrl: "https://<PATH>",
    model3DUrl: "https://<PATH>"
  },
}

How to use​

Usage​

Methods​

addComponent​

removeComponent​

destroy​

Events​

JOINED​

LEFT​

LOCAL_JOINED​

LOCAL_LEFT​

LOCAL_UPDATED​

LIST_UPDATED​

SAME_ACCOUNT_ERROR​

MOUNT​

UNMOUNT​

Type Definitions​

Avatar​

ComponentNames​

Group​

Participant​

How to use

Usage

Methods

`addComponent`

`removeComponent`

`destroy`

Events

`JOINED`

`LEFT`

`LOCAL_JOINED`

`LOCAL_LEFT`

`LOCAL_UPDATED`

`LIST_UPDATED`

`SAME_ACCOUNT_ERROR`

`MOUNT`

`UNMOUNT`

Type Definitions

`Avatar`

`ComponentNames`

`Group`

`Participant`