Skip to main content

Initialization

Overview​

The SuperVizRoom component serves as the foundational element that enables real-time, multi-user interactions within your application. By integrating this component, you establish a virtual space—referred to as a "room"—where participants can join, interact, and collaborate seamlessly.

How to use​

To start using a room, you’ll need to import and call the library’s constructor method, passing your DEVELOPER_KEY as a parameter and the options object.

If you don’t have a DEVELOPER_KEY, you can see how to obtain one on the developer portal in our "Setting Up Your Account" section in our documentation.

To add a room to your web page, 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>",
        avatar: {
          "imageUrl": "https://<PATH>",
          "model3DUrl": "https://<PATH>",
        }
      },
      customColors: {
        'sv-primary-900': '16 29 70',
        'sv-primary-200': '141 164 239',
        'sv-primary': '58 92 204',
        'sv-gray-800': '250 250 252',
        'sv-gray-700': '233 229 239',
        'sv-gray-600': '201 196 209',
        'sv-gray-500': '174 169 184',
        'sv-gray-400': '126 122 136',
        'sv-gray-300': '87 83 95',
        'sv-gray-200': '57 54 62',
        'sv-gray-100': '38 36 42',
      },
    });

    return room;
  }

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

NameTypeDescription
roomIdstringRequired. 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.

Default value: false
groupGroupRequired. You can organize your participants into groups. Usually, a group is a company or organization.
participantParticipantRequired. An object describing the user that will participate in the room.
customColorsColorsVariablesObject to customize the color scheme of your application.
debugbooleanEnable 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 Video Conference or Real-time Mouse Pointers. 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([params...]);

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:

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

function onParticipantJoined(participant) {
	// do something
}

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

TypeDescription
ParticipantThe 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:

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

function onParticipantLeft(participant) {
	// do something
}

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

TypeDescription
ParticipantThe 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:

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

function onParticipantLocalJoin(participant) {
	// do something
}

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

TypeDescription
ParticipantParticipant 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:

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

function onParticipantLocalLeft(participant) {
	// do something
}

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

TypeDescription
ParticipantParticipant 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:

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

function onParticipantLocalUpdate(participant) {
	// do something
}

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

TypeDescription
ParticipantParticipant 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:

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

function onListUpdate(participants) {
	// do something
}

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

TypeDescription
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:

room.subscribe('participant.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:

room.subscribe('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:

room.subscribe('unmount', onComponentUnmouted);

function onComponentUnmouted() {
	// do something
}

Type Definitions​

Avatar​

Type: object

While the SuperViz SDK provides a range of default 3D avatars for meetings, you have the flexibility to enrich this experience by adding your custom avatar for participants.

NameTypeDescription
imageUrlstringRequired. Path to the thumbnail image of the 3D model.
Supported formats: .png and .jpg.
model3DUrlstringPath 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.

ColorsVariables​

Type: object

Default value: SuperViz default colors.

You can customize the color scheme to create your theme. The color variables are represented as RGB values. For additional information on how to personalize, please refer to the documentation on how to theme your application.

Example:

customColors: {
  svBlack: "#ff0000",
  svDanger: "#ff0000",
  svGray: "#ff0000",
  svGray100: "#ff0000",
  svGray200: "#ff0000",
  svGray300: "#ff0000",
  svGray400: "#ff0000",
  svGray500: "#ff0000",
  svGray600: "#ff0000",
  svGray700: "#ff0000",
  svGray800: "#ff0000",
  svPrimary: "#ff0000",
  svPrimary200: "#ff0000",
  svPrimary900: "#ff0000",
  svSecondary: "#ff0000",
  svSuccess: "#ff0000",
  svWhite: "#ff0000",
}

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:

NameValueComponent
ComponentNames.COMMENTScommentsContextual Comments
ComponentNames.PRESENCEpresenceIndicates that any presence component is active (Mouse-Pointers, Who-is-Online, or Real-time Data Engine).
ComponentNames.PRESENCE_AUTODESKpresence3dAutodeskPresence 3D Autodesk
ComponentNames.PRESENCE_MATTERPORTpresence3dMatterportPresence 3D Matterport
ComponentNames.PRESENCE_THREEJSpresence3dThreejsPresence 3D Three.js
ComponentNames.REALTIMErealtimeReal-time Data Engine
ComponentNames.VIDEO_CONFERENCEvideoConferenceVideo Conference
ComponentNames.WHO_IS_ONLINEwhoIsOnlineWho-is-Online

Group​

Type: object

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

NameTypeDescription
idstringA unique ID that identifies the group. Usually, this ID matches your internal ID of a specific company or organization.
namestringThe 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.

NameTypeDescription
idstringRequired. Identifier of the participant who is entering the room. Usually, this ID matches the internal ID of your users.
avatarAvatarParticipant avatar information.
avatarConfigunknownRead-only. Avatar configuration, The same configurations passed when creating an Autodesk Viewer, Matterport, or Three.js avatar on Presence 3D.
colorstringRead-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.
activeComponentsComponentNames[]Read-only. List of active components that the participant has entered.
isHostbooleanRead-only. Indicates if the participant is the current host of the room.
namestringRequired. The name of the participant who will enter the room.
typeParticipantTypeRead-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>"
  },
}