@superviz/immersive-library NPM

Immersive library

About

@superviz/immersive-library is a package that abstracts all operations and management of SuperViz's 3D spaces including real time synchronization.

Getting Started

ImmersiveFacade is the main entry point to access all library functionalities. It provides all methods and flags that developers need to start integrating with SuperViz's 3D spaces. To get an ImmersiveFacade instance, you'll need to import the library builder method and call it, passing your API key, user information and the wrapper ID that you will use to render the 3D space.

example:

import ImmersiveLibrary from '@superviz/immersive-library';

const library = await ImmersiveLibrary(
 '<YOUR API KEY>',
 {
   wrapperId: '<WRAPPER ID>',
   userInfo: {
     externalUserId: '<YOUR APP UNIQUE USER ID>',
     name: '<USER NAME>',
   },
 }
);

NOTES:

It's recommended to use an empty div element with a unique id as a wrapper.
The user information will be used to identify different users inside the 3D space.

Entering a 3D Space

With the library instance configured, it's possible to join a 3D room by using the enterRoom method. The only required parameter is the room id that the user needs to join.

library.enterRoom('<ROOM ID>');

NOTES:

The room id controls which room the users will join. By using the same room id with different users, developers allow them to interact inside the same virtual space session.
The 3D space that will be loaded is the last used in the room identified by the id.

Listening to Events

Immersive library provides some methods to listen to events that can be important to different use cases. They all share the same call pattern and are available as soon as you instantiate the library's facade.

function listener(event) {
 // listener code...
}

// Subscribe to an event update
library.subscribeToEvent(listener);
 
// Unsubscribe from an event update
library.unsubscribeFromEvent(listener);

Below are listed all supported subscribers that developers can use:

subscribeToUserJoined: Notifies regarding a user joined the 3D space;
subscribeToUserLeave: Notifies regarding a user left the 3D space;
subscribeToUserListUpdate: Notifies regarding user properties changes;
subscribeToAmountOfParticipants: Notifies regarding amount of users inside the virtual space;
subscribeToHostChange: Notifies regarding a user has became space host;
subscribeToStateUpdate: Notifies regarding library states;
subscribeToRoomInfoUpdated: Notifies regarding room properties change;

NOTE:

Above are listed only the subscribers, to unsubscribe from an event update, just replace subscribeTo at the beginning of the method name with unsubscribeFrom.

Library state

Through subscribeToStateUpdate the immersive library emits the library state changes. Below are all the states that can be issued:

States

INITIALIZING: Initializing the library;
READY_TO_START: Ready to call enterRoom;
CONNECTING: Connecting to realtime service to fetch model information;
LOADING_MODEL: The 3D model is loading or changing;
CONNECTED: Connected in real-time and 3D service is loaded;
ERROR: Realtime service or 3D model error;
RETRYING: Trying to reconnect to the realtime service;

States Reasons

LOBBY_SERVER_NOT_REACHEABLE: Realtime Lobby server is not reachable. This can be caused due to connection issues or port/protocol blocking by some network element;
LOBBY_CONNECTION_ERROR: Unable to establish connection with lobby server due to connection issues;
ROOM_CONNECTION_FAILED: Unable to enter realtime room due to connection issues;
LOST_CONNECTION: Lost connection to realtime room;
UNABLE_TO_LOAD_ROOM_INFO: Could not load room information. This can occurr if the room has not beign previously created by SuperViz's create room endpoint;
UNABLE_TO_LOAD_FRAME: Failed to initialize immersive frame. This can only occur if https://immersive.superviz.com is not reacheable;
UNABLE_TO_LOAD_SCENE: Unable to load 3D environment due to connection issues and/or problems with 3D rendering;
SCENE_NOT_AVAILABLE_TO_USE: Scene is not available for use. This can occurr if a forge model is not ready to be loaded;
UNABLE_TO_LOAD_SCENE_RESOURCES: Unable to load scene resources. This can occurr if forge service is not reachable and/or has encountered an error;
AUTHENTICATION_FAILED: Authentication error. Check your developer api key and connection;

NOTE:

To abstract these states the immersive library exports enums, which are the LibraryStateTypes for the States and the LibraryStateReasonTypes for the States Reasons

Methods

Change content

The changeContent method allows developers to change the current 3D space to all participants. It takes the content type and content data.

library.changeContent('<CONTENT TYPE>','<CONTENT_DATA>');

Change host

The changeHost method allows developers to change the user who will be the host of the 3D space, it takes the ID of the user who will be the host.

library.changeHost('<USER ID>');

Follow user

The followUser method makes all users follow a user through the 3D environment, the method takes the ID of the user that will be followed.

library.followUser('<USER ID>');

Go to user

The goToUser method takes you to the position of another user in 3D space, the method takes the ID of the user you want to find.

library.goToUser('<USER ID>');

Gather all

The gatherAll method should only be used by the user who is the host, it serves to gather all users in the position that the host is in the 3D environment.

library.gatherAll();

Destroying the Library

When users want to exit the virtual space or your app needs to destroy the library instance for a given reason, the destroy method should be called. It takes no arguments and it will destroy all library references, disconnect from the realtime server and remove the 3D rendered from the wrapper div.