Version: Version 2.0

Room

The Room component is the core element enabling video conference and real-time collaboration within your application. By integrating a room, you create a virtual space where users, or "participants," can join a room.

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 { createRoom } from "@superviz/room";

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

  return room;
}

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

Name	Type	Description
`developerToken`	`string`	Required. Your develper token. You can find it on your dashboard.
`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]*`
`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`

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`

The addComponent method allows you to add a component such as video conference to the room. You can add multiple components to the same room including components from SuperViz collaboration.

Example:

import { MousePointers } from "@superviz/collaboration";

const mousePointers = new MousePointers("my-id");

room.addComponent(mousePointers);

Parameters:

Type	Description
`component`	Required. Pass the component instance you want to add to the room.

`removeComponent`

The removeComponent method allows you to remove a component from the room.

Example:

// if a video instance has been added to the room, then we can remove it
room.removeComponent(mousePointers);

`getParticipants`

Retrieves the list of participants in the room.

Example:

room.getParticipants().then((participants) => {
  console.log("Participants:", participants);
});

Returns: Promise<Participant[]>

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

Type	Description
`Participant[]`	Array of participants in the room

Example:

[
  {
    "id": "USER_ID_1",
    "email": "USER_EMAIL",
    "name": "USER_NAME",
    "activeComponents": ['videoConference'],
    "type": "host",
    "avatar": {
        "imageUrl": "https://<PATH>",
    }
  },
  {
    "id": "USER_ID_2",
    "email": "USER_EMAIL",
    "name": "USER_NAME",
    "activeComponents": ['videoConference'],
    "type": "host",
    "avatar": {
        "imageUrl": "https://<PATH>",
    }
  },
];

`leave`

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

room.leave();

Events

`RoomEvent`

You can subscribe to the following Room events:

Event	String Equivalent	Description
`UPDATE`	`'room.update'`	Triggered when the room updates.
`ERROR`	`'room.error'`	Triggered when an error occurs.

_{^*
Note for CDN Users: Use the string equivalent directly in room.subscribe().}

`UPDATE`

Triggered when the room updates.

Usage Example:

room.subscribe(RoomEvent.UPDATE, onRoomUpdate);

function onRoomUpdate(roomState) {
  // do something
}

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

Type	Description
`RoomState`	Room state that triggered the event.

Example:

{
    "status": RoomState.CONNECTED
}

`ERROR`

Triggered when an error occurs.

Usage Example:

room.subscribe(RoomEvent.ERROR, onRoomError);

function onRoomError(error) {
  // do something
}

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

Type	Description
`RoomError`	Room error that triggered the event.

Example:

{
    "code": "auth_error",
    "message": "[SuperViz] Room initialization failed: this website's domain is not whitelisted."
}

`ParticipantEvent`

You can subscribe to the following Participant events:

Event	String Equivalent	Description
`MY_PARTICIPANT_JOINED`	`'my-participant.joined'`	Triggered when the local participant enters the room.
`MY_PARTICIPANT_LEFT`	`'my-participant.left'`	Triggered when the local participant leaves the room.
`MY_PARTICIPANT_UPDATED`	`'my-participant.updated'`	Triggered when the local participant updates.
`PARTICIPANT_JOINED`	`'participant.joined'`	Triggered when a participant enters the room.
`PARTICIPANT_LEFT`	`'participant.left'`	Triggered when a participant leaves the room.
`PARTICIPANT_UPDATED`	`'participant.updated'`	Triggered when a participant updates.

_{^*
Note for CDN Users: Use the string equivalent directly in room.subscribe().}

`MY_PARTICIPANT_JOINED`

Triggered when the local participant enters the room.

Usage Example:

room.subscribe(ParticipantEvent.MY_PARTICIPANT_JOINED, onMyParticipantJoined);

function onMyParticipantJoined(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",
    "name": "USER_NAME",
    "activeComponents": [],
    "slot": {
        "index": 2,
        "color": "#878291",
        "textColor": "#fff",
        "colorName": "gray",
        "timestamp": 1736161104631
    }
}

`MY_PARTICIPANT_LEFT`

Triggered when the local participant leaves the room.

Usage Example:

room.subscribe(ParticipantEvent.MY_PARTICIPANT_LEFT, onMyParticipantLeft);

function onMyParticipantLeft(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",
    "name": "USER_NAME",
    "activeComponents": [],
    "slot": {
        "index": 2,
        "color": "#878291",
        "textColor": "#fff",
        "colorName": "gray",
        "timestamp": 1736161104631
    }
}

`MY_PARTICIPANT_UPDATED`

Triggered when the local participant updates.

Usage Example:

room.subscribe(ParticipantEvent.MY_PARTICIPANT_UPDATED, onMyParticipantUpdated);

function onMyParticipantUpdated(participant) {
  // do something
}

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

Type	Description
`Participant`	Participant that was updated.

Example:

{
    "id": "USER_ID",
    "name": "USER_NAME",
    "activeComponents": [],
    "slot": {
        "index": 2,
        "color": "#878291",
        "textColor": "#fff",
        "colorName": "gray",
        "timestamp": 1736161104631
    }
}

`PARTICIPANT_JOINED`

Triggered when a participant enters the room.

Usage Example:

room.subscribe(ParticipantEvent.PARTICIPANT_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",
    "name": "USER_NAME",
    "activeComponents": [],
    "slot": {
        "index": 2,
        "color": "#878291",
        "textColor": "#fff",
        "colorName": "gray",
        "timestamp": 1736161104631
    }
}

`PARTICIPANT_LEFT`

Triggered when a participant leaves the room.

Usage Example:

room.subscribe(ParticipantEvent.PARTICIPANT_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",
    "name": "USER_NAME",
    "activeComponents": [],
    "slot": {
        "index": 2,
        "color": "#878291",
        "textColor": "#fff",
        "colorName": "gray",
        "timestamp": 1736161104631
    }
}

`PARTICIPANT_UPDATED`

Triggered when a participant updates.

Usage Example:

room.subscribe(ParticipantEvent.PARTICIPANT_UPDATED, onParticipantUpdated);

function onParticipantUpdated(participant) {
  // do something
}

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

Type	Description
`Participant`	Participant that was updated.

Example:

{
    "id": "USER_ID",
    "name": "USER_NAME",
    "activeComponents": [],
    "slot": {
        "index": 2,
        "color": "#878291",
        "textColor": "#fff",
        "colorName": "gray",
        "timestamp": 1736161104631
    }
}

Type Definitions

`Participant Initialization`

Type: object

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

Name	Type	Description
`id`	`string`	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]*`
`email`	`string`	The email of the participant who will enter the room.
`name`	`string`	The name of the participant who will enter the room.
`avatar`	`Avatar`	Participant avatar information.

Example:

{
    "id": "USER_ID",
    "email": "USER_EMAIL",
    "name": "USER_NAME",
    "avatar": {
        "imageUrl": "https://<PATH>",
        "model3DUrl": "https://<PATH>",
    }
}

`RoomError`

Type: object

An object describing the room error.

Name	Type	Description
`code`	`string`	The error code.
`message`	`string`	The error message.

Example:

{
    "code": "auth_error",
    "message": "[SuperViz] Room initialization failed: this website's domain is not whitelisted."
}

`RoomState`

Type: object

An object describing the room state.

Name	Type	Description
`status`	`string`	The room state. Options: `CONNECTED`, `CONNECTING`, `DISCONNECTED`, `CONNECTION_ERROR`, `RECONNECTING`, `RECONNECT_ERROR`

Example:

{
    "status": "CONNECTED"
}

`Participant`

Type: object

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

Name	Type	Description
`id`	`string`	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]*`
`email`	`string`	The email of the participant who will enter the room.
`activeComponents`	`ComponentNames[]`	List of active components that the participant has entered.
`name`	`string`	The name of the participant who will enter the room.
`avatar`	`Avatar`	Participant avatar information.

Example:

{
    "id": "USER_ID",
    "email": "USER_EMAIL",
    "name": "USER_NAME",
    "activeComponents": ['videoConference'],
    "type": "host",
    "avatar": {
        "imageUrl": "https://<PATH>",
    }
}

`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.VIDEO_CONFERENCE`	`videoConference`	Video Conference or Video Huddle
`ComponentNames.WHO_IS_ONLINE`	`whoIsOnline`	Who-is-Online
`ComponentNames.COMMENTS`	`comments`	Contextual Comments
`ComponentNames.PRESENCE`	`presence`	Mouse Pointers
`ComponentNames.PRESENCE_AUTODESK`	`presence3dAutodesk`	Presence 3D Autodesk
`ComponentNames.PRESENCE_MATTERPORT`	`presence3dMatterport`	Presence 3D Matterport
`ComponentNames.PRESENCE_THREEJS`	`presence3dThreejs`	Presence 3D Three.js

`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>",
}

How to use​

Usage​

Methods​

addComponent​

removeComponent​

getParticipants​

leave​

Events​

RoomEvent​

UPDATE​

ERROR​

ParticipantEvent​

MY_PARTICIPANT_JOINED​

MY_PARTICIPANT_LEFT​

MY_PARTICIPANT_UPDATED​

PARTICIPANT_JOINED​

PARTICIPANT_LEFT​

PARTICIPANT_UPDATED​

Type Definitions​

Participant Initialization​

RoomError​

RoomState​

Participant​

ComponentNames​

Avatar​

How to use

Usage

Methods

`addComponent`

`removeComponent`

`getParticipants`

`leave`

Events

`RoomEvent`

`UPDATE`

`ERROR`

`ParticipantEvent`

`MY_PARTICIPANT_JOINED`

`MY_PARTICIPANT_LEFT`

`MY_PARTICIPANT_UPDATED`

`PARTICIPANT_JOINED`

`PARTICIPANT_LEFT`

`PARTICIPANT_UPDATED`

Type Definitions

`Participant Initialization`

`RoomError`

`RoomState`

`Participant`

`ComponentNames`

`Avatar`