Skip to main content
Version: Latest

API reference

Constructor params​

const sdk = await SuperVizSdk.init(<TOKEN>, {
  group: {
    id: string,
    name: string,
  },
  participant: {
    id: string,
    name: string | undefined,
    type: ParticipantType,
    color: string | undefined,
    avatar: {
      model: "YOUR_AVATAR_URL.gltf",
    } | undefined,
  },
  roomId: string,
  debug: boolean | undefined,
  shouldKickparticipantsOnHostLeave: boolean | undefined
  camsOff: boolean | undefined,
  screenshareOff: boolean | undefined,
  defaultAvatars: boolean | undefined,
  enableFollow: boolean | undefined,
  enableGoTo: boolean | undefined,
  enableGather: boolean | undefined,
  language: string | undefined,
  locales: Locale[] | undefined,
  customColors: ColorsVariables | undefined,
  isMouseEnabled: boolean | undefined,
  isLaserEnabled: boolean | undefined,
  avatars: Avatar[] | undefined,
  camerasOrientation: string | undefined,
  skipMeetingSettings: boolean | undefined,
  disableCameraOverlay: boolean | undefined,
  devices: {
    audioInput: boolean | undefined,
    audioOutput: boolean | undefined,
    videoInput: boolean | undefined,
  }
});

group​

You can organize your participants into groups. Usually, a group is a company or organization.

  • id: A unique ID that identifies the group. Usually, this ID matches your internal ID of a specific company or organization.
  • name: The name of the group.

participant​

  • id: Identifier of the participant who is entering the meeting. Usually, this ID matches your internal ID of your users. If a participant is a guest you should create a unique ID for this participant as well.
  • name: The name of the participant who will enter the meeting room. If added a name, the name in the meeting settings will be prefilled automatically.
  • type: The user type determines the user's role in the meeting:
  • avatar.model: the URL of the .gltf or .glb model you want to be the avatar of the current participant instance. Plugins will use this URL to create the avatar.
  • color: Unique color for the participant in the meeting, is used to identify the user cursor and avatar in 3D space. The color is set automatically when the participant joins the meeting.

roomId​

This ID is the unique meeting room ID.

shouldKickParticipantsOnHostLeave​

Determines whether the meeting should end when there is no host in the meeting room. The default value for this option is true.

debug​

Enable SDK logs in the client console.

camsOff​

Disables the participant’s camera, also does not show the cameras of other participants that are in the room. default: false

screenshareOff​

Disables screenshare for the participant. But it keeps showing the screnshare of other participants in the room. default: false

defaultAvatars​

Enable the avatar screen selection for participant can choose one to use in the meeting. default: false

The avatar screen selection only shows when the participant doesn’t has participant.avatar.model and this option is true.

enableFollow​

Show the follow buttons on the cameras. default: false

enableGoTo​

Show the go to button on the cameras. default: false

enableGather​

Show the gather button on the cameras. default: false

offset​

The offset assists in positioning the iframe of the video, the measurements can be passed to top, bottom, left and right.

example:

offset: {
  top: 0,
  bottom: 0,
  left: 0,
  right: 0,
}

language​

The default frame meeting language. It can be changed to a custom language, but you must add the custom language to the locale list.

The default is `en'.

locales​

The list of languages that is available in the meeting overlay. The default is en.

You can see more here: Locales

customColors​

Set the custom colors for the meeting overlay. The default is undefined.

You can see more here: Custom colors

isMouseEnabled​

Determines whether the mouse position should be synchronized and displayed to other users in the 3D space. The default value for this option is true.

Info!

Please note that this flag only applies if you use one of our default plugins.

isLaserEnabled​

Determines whether the mouse position should be synchronized and displayed to other users in the 3D space. The default value for this option is true.

Info!

Please note that this flag only applies if you use one of our default plugins.

avatars​

The SuperViz SDK provides a list of default avatars for the meeting, but you can customize the list with your own avatars.

The format of the avatar list is:

[
  {
    model: string,
    thumbnail: string,
  },
];

Example:

[
  {
    model:
      "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Duck/glTF-Binary/Duck.glb",
    thumbnail:
      "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Duck/screenshot/screenshot.png",
  },
];
Info!

Please note that this flag only applies if you use one of our default plugins.

camerasOrientation​

Determines whether you want to use vertical or horizontal camera layout. The default value for this option is vertical.

camerasOrientation

skipMeetingSettings​

Determines whether to skip the default meeting setup screen and directly join a meeting. The participant enters without a camera and with a mute microphone, he can change this later within a meeting.

disableCameraOverlay​

Determines to be able to remove the entire part of cameras, toolbar of the meeting, in this way it is not necessary permissions of cameras or microphones.

devices​

Determines whether the participant can use the mentioned devices, if he chooses to disable one, it will not appear on the Meeting Setup screen and the user will not be able to activate these features within the meeting. It can be used to create a meeting without microphones or without cameras for example.

Methods​

The SuperViz SDK provides its own real-time service that can be used to synchronize properties between all participants within the meeting room. It is possible to add custom properties as well as listen to events that are emitted by the SDK.

Subscribing to listeners​

For both custom events or events that the SDK emits by default, the subscription syntax is the same.

To subscribe to an event, add a callback function that will be called when that event is dispatched.

sdk.subscribe(<EVENT_NAME>, callbackfn);

Listeners​

Default SDK Events​

All listeners are available in the message enum that the SDK exports to the client.

import {
  MeetingEvent,
  DeviceEvent,
  RealtimeEvent,
  MeetingState,
  Participant,
} from "@superviz/sdk";

MEETING_SAME_PARTICIPANT_ERROR​

Dispatched when a participant tries to join the same meeting at the same time. In this case, the SDK dispatches the error and destroys the first instance of the SDK, leaving only the last instance that is currently being used.

sdk.subscribe(MeetingEvent.MEETING_SAME_PARTICIPANT_ERROR, onSameParticipantError);

// Callback function
onSameParticipantError() {
  alert('Same account error - Someone has joined the meeting with the same participant ID');
},

MEETING_DEVICES_CHANGE​

Dispatched when the local participant’s device has changed. This event also dispatches device errors, such as when they are not found or when the participant does not allow access to them.

sdk.subscribe(MeetingEvent.MEETING_DEVICES_CHANGE, onDevicesChange);

// Callback function
onDevicesChange(state: DeviceEvent) {
  if (state === DeviceEvent.DEVICES_BLOCKED) {
    alert('Please, allow SuperViz to use your camera and microphone to start meeting');
  }
},

MEETING_PARTICIPANT_AMOUNT_UPDATE​

Dispatched when the number of participants inside the meeting room changes.

sdk.subscribe(MeetingEvent.MEETING_PARTICIPANT_AMOUNT_UPDATE, onParticipantAmountUpdate);

onParticipantAmountUpdate(count: number) {
   // count is the number of participants inside the meeting
   // do something
},

MEETING_PARTICIPANT_LIST_UPDATE​

Dispatched when the list of participants inside the meeting room changes. Whether a participant enters or leaves the room and when any participant is updated.

sdk.subscribe(MeetingEvent.MEETING_PARTICIPANT_LIST_UPDATE, onParticipantListUpdate);

onParticipantListUpdate(list: Array<Participant>) {
  // list is an array of participants inside the meeting
  // do something
},

MEETING_PARTICIPANT_JOINED​

Dispatched when a participant enters the meeting room.

sdk.subscribe(MeetingEvent.MEETING_PARTICIPANT_JOINED, onParticipantJoined);

onParticipantJoined(participant: Participant) {
    // participant: Participant
  // do something
}

MEETING_PARTICIPANT_LEFT​

Dispatched when a participant leaves the meeting room.

sdk.subscribe(MeetingEvent.MEETING_PARTICIPANT_LEFT, onParticipantLeft);

onParticipantLeft(participant: Participant) {
    // participant: Participant
  // do something
}

MEETING_KICK_PARTICIPANTS​

Dispatched when the host leaves the meeting room and there are no other candidate hosts left in the meeting. This event is dispatched and then the meeting ends automatically after 1 minute.

To change this behavior, pass shouldKickParticipantsOnHostLeave in the SDK initialization method.

Reference: shouldKickParticipantsOnHostLeave

sdk.subscribe(MeetingEvent.MEETING_KICK_PARTICIPANTS, onMeetingKickParticipants);

onMeetingKickParticipants() {
  // do something
}

MEETING_STATE_UPDATE​

When the state of the meeting room changes, this event is dispatched.

sdk.subscribe(MeetingEvent.MEETING_STATE_UPDATE, onMeetingStateDidChange);

onMeetingStateDidChange(newState: MeetingState) {
  // do something
}

MEETING_HOST_CHANGE​

During the meeting control of the meeting can be passed from one user to another. This event is called by passing the object of the new meeting host as a parameter.

sdk.subscribe(MeetingEvent.MEETING_HOST_CHANGE, onMeetingHostDidChange);

onMeetingHostDidChange(payload: RealtimeMessage[]) {
  // payload is the realtime message array, containing realtime messages when happened in the last second
  // do something
}

MY_PARTICIPANT_UPDATED​

Dispatched when a change is made to the local participant.

sdk.subscribe(MeetingEvent.MY_PARTICIPANT_UPDATED, onLocalParticipantDidChange);

onLocalParticipantDidChange(participant: Participant) {
  // do something
}

MY_PARTICIPANT_LEFT​

Dispatched when the local participant leaves the meeting room.

sdk.subscribe(MeetingEvent.MY_PARTICIPANT_LEFT, onLocalParticipantLeft);

onLocalParticipantLeft(participant: Participant) {
  // do something
}

MY_PARTICIPANT_JOINED​

Dispatched when the local participant joins the meeting room.

sdk.subscribe(MeetingEvent.MY_PARTICIPANT_JOINED, onLocalParticipantJoin);

onLocalParticipantJoin(participant: Participant) {
  // do something
}

REALTIME_GO_TO_PARTICIPANT​

Dispatched when a participant clicks on the camera to go to another participant.

sdk.subscribe(RealtimeEvent.REALTIME_GO_TO_PARTICIPANT, onGoToClicked);

onGoToClicked(payload: RealtimeMessage[]) {
  // payload is the realtime message array, containing realtime messages when happened in the last second
  // do something
}

REALTIME_GATHER​

Dispatched when a host clicks on the gather button.

sdk.subscribe(RealtimeEvent.REALTIME_GATHER, onGather);

onGather() {
  // do something
}

REALTIME_FOLLOW_PARTICIPANT​

Dispatched when a hosts clicks on the follow button.

sdk.subscribe(RealtimeEvent.REALTIME_FOLLOW_PARTICIPANT, onFollowClicked);

onFollowClicked(payload: RealtimeMessage[]) {
  // payload is the realtime message array, containing realtime messages when happened in the last second
  // do something
}

Syncing custom properties​

You can declare your own properties that will be synchronized within the meeting room. Custom sync properties are generally used to sync actions between participants. Examples could be, changing scenes, selecting elements, changing the view method, opening hotspots etcetera.

You can find more information about the sync properties in the realtime engine page.

sdk.subscribe('syncPropertyName', onSyncPropertyChange);

onSyncPropertyChange(payload: RealtimeMessage[]) {
  // payload is the realtime message array, containing realtime messages when happened in the last second
  // do something
}

To change the value of the property in the meeting room, pass the new value.

sdk.setSyncProperty("syncPropertyName", "new value");

It’s important to notice that maximum allowed message size is 10Kb.

Retrive saved data​

You also retrieve saved data in the sync engine and store the last message of each type in a key-value pair list. Find more information about the last message history in the realtime retrieve saved data page.

Setting a sync property:

sdk.setSyncProperty("syncPropertyName", "new value");

Retrieving the last message from that key:

sdk.fetchSyncProperty("syncPropertyName"); // Promise<RealtimeData>

Retrieving all history:

sdk.fetchSyncProperty(); // Promise<Record<string, RealtimeMessage>>

Call 'Go-to' method​

In case you want to build your own Go-to button, you can call the goTo method. This method would work in the same way as if a participant clicks on the Go-to button on the camera overlay.

To listen to the event see REALTIME_GO_TO_PARTICIPANT.

sdk.goTo(participantId: string);

Tip!

In case you are using one of our plugins, the Go-to functionality will be called automatically.

Call 'Gather' method​

In case you want to build your own Gather button, you can call the gather method. This method would work in the same way as if a host clicks one of the Gather buttons on the camera overlay.

To listen to the event see REALTIME_GATHER.

sdk.gather();
Tip!

In case you are using one of our plugins, the Gather functionality will be called automatically.

Call 'Follow' method​

In case you want to build your own Follow button, you can call the follow method. This method would work in the same way as if a participant clicks on one of the follow buttons on the camera overlay.

To listen to the event see REALTIME_FOLLOW_PARTICIPANT.

sdk.follow(participantId: string);

To unfollow you need to pass an empty string to the follow method.

sdk.follow("");
Tip!

In case you are using one of our plugins, the Follow functionality will be called automatically.

Destroy​

When a participant leaves the meeting room or your application needs to destroy the library instance for a certain reason, the destroy method must be called. It will unmount the video frame and destroy all SDK references.

sdk.destroy();