How to build a sales tool with Matterport SDK and SuperViz

In this tutorial, we will guide you through creating a sales tool with Matterport and SuperViz. This tool allows sales teams to interactively present Matterport 3D spaces to clients in real-time, complete with video conferencing and live presence features. Whether you're showcasing real estate, virtual tours, or any 3D environment, this tool enhances the sales experience by enabling collaborative navigation and communication within the 3D space.

We'll demonstrate how to set up Matterport with SuperViz to enable real-time presence, video conferencing, and interactive features that help sales teams engage with clients more effectively.
Let's get started!

Step 1: Set Up Your React Application

To begin, you'll need to set up a new React project where we will integrate SuperViz and Matterport Viewer.

1. Create a New React Project

First, create a new React application using Create React App with TypeScript.

1
npm create vite@latest matterport-sales-tool -- --template react-ts
2
cd matterport-sales-tool

2. Install Required Libraries

Next, install the necessary libraries for our project:

1
npm install @superviz/sdk @superviz/matterport-plugin uuid

• @superviz/sdk: SDK for integrating real-time collaboration features, including video conferencing and presence.
• @superviz/matterport-plugin: Plugin for adding SuperViz presence and interaction features to a Matterport Viewer.
• uuid: A library for generating unique identifiers, useful for creating unique participant IDs.

3. Configure tailwind

In this tutorial, we'll use the Tailwind css framework. First, install the tailwind package.

1
npm install -D tailwindcss postcss autoprefixer
2
npx tailwindcss init -p

We then need to configure the template path. Open tailwind.config.js in the root of the project and insert the following code.

1
/** @type {import('tailwindcss').Config} */
2
export default {
3
content: [
4
"./index.html",
5
"./src/**/*.{js,ts,jsx,tsx}",
6
],
7
theme: {
8
extend: {},
9
},
10
plugins: [],
11
}

Then we need to add the tailwind directives to the global CSS file. (src/index.css)

1
@tailwind base;
2
@tailwind components;
3
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key and Matterport application key. These credentials will be used to authenticate your application with SuperViz and Matterport services.

1
VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY
2
VITE_MATTERPORT_KEY=YOUR_MATTERPORT_KEY

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and Matterport Viewer, and handle real-time presence and video conferencing.

1. Implement the App Component

Open src/App.tsx and set up the main application component using SuperViz to manage the collaborative environment.

1
import { v4 as generateId } from 'uuid';
2
import { useCallback, useEffect, useRef } from "react";
3
import SuperVizRoom, { VideoConference } from '@superviz/sdk';
4
import { Presence3D } from '@superviz/matterport-plugin';
5
import type { MpSdk } from '@superviz/matterport-plugin/dist/common/types/matterport.types.d.ts';

Explanation:

• Imports: Import necessary components from React, SuperViz SDK, Matterport Plugin, and UUID for managing state, initializing SuperViz, enabling video conferencing, and handling Matterport SDK interactions.

2. Define Constants

Define constants for the API key, Matterport key, and room ID.

1
const apiKey = import.meta.env.VITE_SUPERVIZ_API_KEY as string;
2
const matterportKey = import.meta.env.VITE_MATTERPORT_KEY as string;
3

4
const ROOM_ID = 'matterport-sales-tool';
5
const PLAYER_ID = generateId();

Explanation:

• apiKey & matterportKey: Retrieves the SuperViz and Matterport API keys from environment variables.
• ROOM_ID & PLAYER_ID: Defines the room ID for the SuperViz session and generates a unique player ID.

3. Create the App Component

Set up the main App component and initialize references for the Matterport SDK.

1
export default function App() {
2
  const matterportSDK = useRef<MpSdk | null>(null);
3

4
  useEffect(() => {
5
    initializeMatterport();
6
  }, []);

Explanation:

• matterportSDK: A ref to store the Matterport SDK instance.
• useEffect: Calls the initializeMatterport function once when the component mounts, setting up the Matterport Viewer.

4. Initialize SuperViz

Create a function to initialize the SuperViz environment and integrate presence and video conferencing.

1
const initializeSuperViz = useCallback(async () => {
2
  const superviz = await SuperVizRoom(apiKey, {
3
    roomId: ROOM_ID,
4
    participant: {
5
      id: PLAYER_ID,
6
      name: 'player-name',
7
    },
8
    group: {
9
      id: 'matterport-sales-tool',
10
      name: 'matterport-sales-tool',
11
    }
12
  });
13

14
  const presence = new Presence3D(matterportSDK.current!);
15
  superviz.addComponent(presence);
16

17
  const video = new VideoConference({
18
    enableFollow: true,
19
    enableGather: true,
20
    enableGoTo: true,
21
    userType: 'host'
22
  });
23

24
  superviz.addComponent(video);
25
}, []);

Explanation:

• initializeSuperViz: An asynchronous function that initializes the SuperViz room, adds the presence component to track user interactions within the 3D space, and integrates video conferencing.
• Presence3D: Manages real-time presence in the Matterport space, showing where each participant is looking or interacting.
• VideoConference: Adds video conferencing with features like follow, gather, and go-to, enhancing the collaborative experience.

5. Initialize Matterport Viewer

Create a function to initialize the Matterport Viewer with the necessary credentials and configurations.

1
const initializeMatterport = useCallback(async () => {
2
  const showcase = document.getElementById('showcase') as MatterportIframe;
3
  const showcaseWindow = showcase.contentWindow as MatterportIframe['window'];
4
  const source = `/vendor/matterport/showcase.html?&play=1&qs=1&applicationKey=${matterportKey}&m=Zh14WDtkjdC`;
5
  showcase.setAttribute('src', source);
6

7
  await new Promise((resolve) => {
8
    showcase.addEventListener('load', async () => {
9
      matterportSDK.current = await showcaseWindow?.MP_SDK.connect(showcaseWindow, matterportKey);
10
      resolve(matterportSDK.current);
11
    });
12
  });
13

14
  initializeSuperViz();
15
}, [initializeSuperViz]);

Explanation:

• initializeMatterport: Loads the Matterport Viewer in an iframe, connects the Matterport SDK, and then initializes SuperViz for real-time collaboration.
• initializeSuperViz: Called after Matterport is initialized to set up presence and video conferencing.

Step 3: Render the Application

Finally, return the JSX structure for rendering the Matterport Viewer and the SuperViz-powered interface.

1
return (
2
  <div className='w-full h-full bg-gray-200 flex items-center justify-center flex-col'>
3
    <header className='w-full p-5 bg-purple-400 flex items-center justify-between'>
4
      <h1 className='text-white text-2xl font-bold'>SuperViz Matterport Sales Tool</h1>
5
    </header>
6
    <main className='w-full h-full flex items-center justify-center relative'>
7
      <iframe id='showcase' className='w-full h-full' />
8
    </main>
9
  </div>
10
);

Explanation:

• Viewer Container: The showcase iframe is where the Matterport Viewer will be rendered, filling the entire screen. This is where users will interact with the 3D space and collaborate in real time.

Step 4: Understanding the Project Structure

Here's a quick overview of how the project structure supports a Matterport sales tool:

1. App.tsx:
   • Initializes the SuperViz environment.
   • Sets up the Matterport Viewer with real-time presence and video conferencing features.
   • Handles the loading of 3D spaces and integration of collaborative tools.
2. Matterport Viewer: Renders the 3D space, allowing users to navigate, inspect, and collaborate in a shared virtual environment.
3. SuperViz Components:
   • Presence3D: Displays real-time presence information, showing where each participant is looking or interacting in the 3D space.
   • VideoConference: Enables video communication within the 3D space, supporting collaborative sales presentations and discussions.

Step 5: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:

1
npm run dev

This command will start the development server and open your application in the default web browser. You can interact with the 3D space and see real-time presence and video conferencing from other participants.

2. Test the Application

• Real-Time Presence: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that presence information is updated in real-time.
• Collaborative Interaction: Test the video conferencing feature by starting a call within the 3D space and interacting with participants.

Summary

In this tutorial, we built a Matterport sales tool using SuperViz for real-time collaboration. We configured a React application to handle 3D space navigation and video conferencing, enabling multiple users to engage in a collaborative sales presentation seamlessly. This setup can be extended and customized to fit various scenarios where real-time collaboration on 3D spaces is required.

Feel free to explore the full code and further examples in the GitHub repository for more details.