Skip to main content

Moving from v4 to v5

This guide is intended to assist you with the update to version 5 of the SuperViz SDK. It will focus on side-by-side comparisons for similar operations between the two versions.

If you need any help when migrating, you can find a dedicated channel on our Discord server, where we can help you with the migration.

Before you start updating, it's important to familiarize yourself with the key changes and improvements introduced in SuperViz SDK v5.

Version 4 end of support​

We are releasing version 5 on November 8th, 2023. We believe that this is the best way to use our SDK, so we won't be supporting version 4 after December 18th, 2023. After this date, applications still using version 4 won’t work as expected.

General Changes​

SuperViz SDK initialization​

The biggest change comes with how we initialize the SDK. With version 4, when you initialize the SDK, you also initialize the video meeting. In the recent version, you need to initialize the video and all other components you want to use separately. With that, some properties have moved to Video Conference or to the Presence3D constructor.

We previously were calling the initialization the SuperVizSDK, and now we are calling it the room.

In the table below you find a list of the properties from v4 compared to its new name/location:

SuperViz Initializer v4Room (previously know as SuperVizSDK) Initializer v5Video ConferencePresence3D
groupHasn't changed.--
group.idHasn't changed.--
group.nameHasn't changed.--
participantHasn't changed.--
participant.nameHasn't changed.--
participant.typeMoved to Video Conference.participantType-
participant.colorDeprecated.--
participant.avatarHasn't changed.--
participant.avatar.modelparticipant.avatar.model3DUrl--
roomIdHasn't changed.--
debugHasn't changed.--
shouldKickparticipantsOnHostLeaveMoved to Video Conference.allowGuests-
camsOffMoved to Video Conference.camsOff-
screenshareOffMoved to Video Conference.screenshareOff-
defaultAvatarsMoved to Video Conference.defaultAvatars-
enableFollowMoved to Video Conference.enableFollow-
enableGoToMoved to Video Conference.enableGoTo-
enableGatherMoved to Video Conference.enableGather-
languageMoved to Video Conference.language-
localesMoved to Video Conference.locales-
customColorsHasn't changed when using v5.1.0.--
isMouseEnabledMoved to Presence3D.-isMouseEnabled
isLaserEnabledMoved to Presence3D.-isLaserEnabled
avatarsMoved to Video Conference.avatars-
camerasPositionMoved to Video Conference.collaborationMode.position-
layoutPositionMoved to Video Conference.collaborationMode.modalPosition-
skipMeetingSettingsMoved to Video Conference.skipMeetingSettings-
disableCameraOverlayDeprecated.--
devicesMoved to Video Conference.devices-
devices.audioInputMoved to Video Conference.devices.audioInput-
devices.audioOutputMoved to Video Conference.devices.audioOutput-
devices.videoInputMoved to Video Conference.devices.videoInput-

3D Plugins​

This change is also reflected in the Autodesk, Matterport, and ThreeJS plugins. Previously you would use loadPlugin() after the participant had joined a room, now you must create an instance of Presence3D (a component that can be found in the plugins packages) and add it to the SDK.

Here is how to load the Autodesk Viewer:

import { Presence3D } from "@superviz/autodesk-viewer-plugin";

Autodesk.Viewing.Initializer(options, async () => {
	const viewerDiv = document.getElementById('forge-viewer');
  const viewer = new Autodesk.Viewing.GuiViewer3D(viewerDiv);

  await viewer.start();

	const autodeskPresence = new Presence3D(viewer, {
	  isAvatarsEnabled: true,
	  isLaserEnabled: true,
	  isNameEnabled: true,
	  avatarConfig: {
	    height: 0,
	    scale: 1,
	    laserOrigin: { x: 0, y: 0, z: 0 },
	  },
	});
	
	room.addComponent(autodeskPresence);
});

If you require additional information on accomplishing this, you can refer to the dedicated documentation page that explains how to initialize the Autodesk viewer.

Custom made plugins​

While we provide plugins for Autodesk, Matterport, or ThreeJS, sometimes you may need to use other libraries or softwares, and we can still help you achieve a great Presence3D experience.

If you have made a custom plugin to connect to SuperViz, you may need to update how you send and receive user positions. Here is what’s changed when making a custom implementation:

import { Realtime } from "@superviz/sdk/lib/components";

// Create an instance of realtime and subscribe to a custom event
const realtime = new Realtime();
room.subscribe(userId, onUserXUpdated);
realTime.subscribe("USER_POSITION_UPDATE", onUserPositionUpdate);

room.addComponent(realtime);

// Define a callback function receiving the user position
onUserXUpdated({ x, y, z }) {
onUserPositionUpdate({ userId, { x, y, z } }) {
  // Update user avatar with position x, y, z
}

// Send the user location every time it updates
room.setSyncProperty(userId, { x: 0, y: 2, z: 0 });
realTime.publish("USER_POSITION_UPDATE", { userId, { x: 0, y: 2, z: 0 }});

Plugin packages compatibility​

Despite the need to update your @superviz/autodesk-viewer-plugin, @superviz/matterport-plugin, and @superviz/threejs-plugin packages, you don’t need to update your instances of Autodesk Viewer, Matterport Bundle and ThreeJS package.

Avatars​

We updated the property's name inside when defining an Avatar, so be sure to update it as well.

	export interface Avatar {
-   model: string;
+   model3DUrl: string;
-   thumbnail: string;
+   imageUrl: string;
  }

Events Subscriptions​

With the recent version, the events are now relatable to each component. Previously you could subscribe only to the SDK events, but now some of these events will not be available from the SDK instance, instead they will be at Video Conference.

The code below shows how to subscribe to the SDK events:

import SuperVizRoom from "@superviz/sdk";

const room = new SuperVizRoom(DEVELOPER_KEY, {...});

room.subscribe("EVENT_NAME", callbackFunction);

The code below shows how to subscribe to the Video Conference events:

import { VideoConference } from "@superviz/sdk/lib/components";

const videoConference = new VideoConference({...});

videoConference.subscribe("EVENT_NAME", callbackFunction);

The table below shows every event, from version 4, and where they should be subscribed:

Events in version 4room.subscribe()
MEETING_DEVICES_CHANGEAvailable at videoConference.subscribe().
MEETING_HOST_CHANGEAvailable at room.subscribe() with the name REALTIME_HOST_CHANGE.
MEETING_KICK_PARTICIPANTSAvailable at videoConference.subscribe().
MEETING_PARTICIPANT_AMOUNT_UPDATEAvailable at videoConference.subscribe().
MEETING_PARTICIPANT_JOINEDAvailable at videoConference.subscribe().
MEETING_PARTICIPANT_LEFTAvailable at videoConference.subscribe().
MEETING_PARTICIPANT_LIST_UPDATEAvailable at videoConference.subscribe().
MEETING_SAME_PARTICIPANT_ERRORAvailable at videoConference.subscribe().
MEETING_STATE_UPDATEAvailable at videoConference.subscribe().
MY_PARTICIPANT_LEFTAvailable at videoConference.subscribe().
MY_PARTICIPANT_JOINEDAvailable at videoConference.subscribe().
MY_PARTICIPANT_UPDATEDDeprecated. You can replace by using the LOCAL_UPDATE event on the room.subscribe() listener.
REALTIME_FOLLOW_PARTICIPANTDeprecated.
REALTIME_GATHERDeprecated.
REALTIME_GO_TO_PARTICIPANTDeprecated.

New events​

Other than the nine events available, we are releasing thirteen new events to create new possibilities for your application. The complete list of new events is available in the version 5 release notes.

Real-time Data Engine​

Like we did with the Video Conference, we moved the Real-time Data Engine away from the SDK instance, now having a new way for you to dispatch and subscribe to your custom events.

As you learned on Events Subscription section on this Migration Guide, subscribing to events had change from components, going to Video Conference and the SDK instance. But what about custom events? We know this is a big part of enabling collaboration among your participants, so we are expanding it.

Now, to publish and subscribe to your custom events, you will use the Real-time Data Engine. The code below displays how to publish and subscribe to your custom events:

import { Realtime } from "@superviz/sdk/lib/components";

// Create an instance of Realtime and add it to your current sdk instance
const realtime = new Realtime();
room.addComponent(realtime);

// Whenever you want to publish one event, you can use the publish method passing a payload
const payload = "your custom payload here";
realTime.publish("<EVENT_NAME>", payload);

// Be sure to subscribe to the event by passing its name and a callback function
realTime.subscribe("<EVENT_NAME>", callbackFunction);
function callbackFunction(payload) {
	// do something
}

As you can see, this is quite simple to implement and a bit familiar on how it’s done in version 4, but we updated a few names. We update the names to make it simpler to understand while making it clear the purpose of the method.

Here is a comparison list of how we have called it in the past and how we are calling it today, make sure to update not only the function name but to use the Real-time Data Engine when calling it.

v4 (on the SDK instance)v5 (on the Real-time Data Engine instance)
fetchSyncProperty()fetchHistory()
setSyncProperty()publish()
subscribe()subscribe()

Deprecated functions​

While we introduce new features, we are also removing some functions. You still can perform the same function, but code changes may be required.

unloadPlugin()​

If you use the method unloadPlugin() on Matterport, ThreeJS, or Autodesk, you can replace it by removing the component, similar to the code below:

const presence3d = new Presence3D();

- room.unloadPlugin();
+ room.removeComponent(presence3d);

getAvatars()​

If you use the method getAvatars(), you can replace it by using the LIST_UPDATED event on the SDK to store the list of participants in a room.

getParticipantsOn3D()​

We have removed this method as an option for our plugins.