How to migrate from SuperViz v4.x to v5.x

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

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 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 as the SuperVizSDK, and now we are calling it as the Room.

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

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.

Autodesk viewer

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.

Matterport

Here is how to load the Matterport viewer:

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

const matterportPresence = new Presence3D(mpSdk, {
  isAvatarsEnabled: true,
  isLaserEnabled: true,
  isNameEnabled: true,
  avatarConfig: {
    height: 0,
    scale: 1,
    laserOrigin: { x: 0, y: 0, z: 0 },
  },
});

room.addComponent(matterportPresence);

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

ThreeJS

Here is how to load the ThreeJS scene:

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

const threeJSPresence = new Presence3D(scene, camera, camera, {
  isAvatarsEnabled: true,
  isLaserEnabled: true,
  isNameEnabled: true,
    isMouseEnabled: true,
    renderLocalAvatar: true,
  avatarConfig: {
    height: 0,
    scale: 1,
    laserOrigin: { x: 0, y: 0, z: 0 },
  },
});

room.addComponent(threeJSPresence);

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

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 everytime 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 properties 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 the version 4, and where they should be subscribed:

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 on how we have called 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.

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.