SDK Bundle

Latest Version

SDK Bundle

What is the SDK Bundle?

It is an extension of the SDK for embeds and provides a framework for deep third-party integration with Matterport models. You get direct access to the 3d engine, renderer, scene graph and more.

Installation

Before installing, you will need to create an SDK key.

To manage keys, log in to your account, navigate to Account Settings -> Developer Tools, and scroll down to “SDK Key Management”. Click “Add an SDK Key” and add any desired local domains to the allow list (for example, localhost and localhost:8080).

To learn more about our developer tools, please visit the Matterport Developer Tools and Pricing

Once you have an SDK key, there are two methods for adding the Bundle SDK to your site:

1. Iframe (standard method)
2. Custom Web Component/NPM package (beta)
   1. Migrating from iframe to web component

Updates

Latest Bundle SDK update: November 20, 2023
See the change log

Iframe Method

Download the latest SDK Bundle package

https://static.matterport.com/showcase-sdk/bundle/23.11.1_webgl-82-g7e8efde062/showcase-bundle.zip

Extract the contents of showcase-bundle.tar.gz to a directory where your files will be served

It is important that you preserve the package’s file organization. We recommend that you keep the bundle files under one directory to make it easy to upgrade in the future.

> cd [path to server root]
> mkdir bundle
> unzip showcase-bundle.zip -d bundle
password:
> ls bundle
css		fonts		js		showcase.html	version.txt
cursors		images		locale		terms
>

Add an iframe to your existing page that targets the showcase.html file of the bundle directory

To avoid css conflicts, we are requiring that the showcase be embedded in an iframe.

Replace [MODEL_SID] with your own.

Add the applicationKey=[YOUR SDK_KEY] URL parameter to provide your sdk key as part of the url.

<iframe id="showcase" width="740" height="480" src="/bundle/showcase.html?m=[MODEL_SID]&applicationKey=[YOUR_SDK_KEY_HERE]" frameborder=”0” allowfullscreen allow="vr"'></iframe>

Connect to the SDK

Add a script to the page to await the loading of showcase. Connect to it once loaded.

const showcase = document.getElementById('showcase');
const showcaseWindow = showcase.contentWindow;
showcase.addEventListener('load', async function() {
  let mpSdk;
  try {
    mpSdk = await showcaseWindow.MP_SDK.connect(showcaseWindow);
  }
  catch(e) {
    console.error(e);
    return;
  }

  console.log('Hello Bundle SDK', mpSdk);
});

Rich Media Content in Tags

The SDK Bundle runs on your domain, therefore, it is necessary for users for the SDK Bundle to purchase their own API Keys with Embed.ly.

Connect using an OAuth Token

Contact Developer Support to enable OAuth for your application.

To connct to a model using an OAuth token, pass an access_token as auth in the options argument to connect.

const showcase = document.getElementById('showcase');
const showcaseWindow = showcase.contentWindow;
const mpSdk = await showcaseWindow.MP_SDK.connect(showcaseWindow, {
  auth: '[access_token]',
});

Web Component Method

About

⚠️ Note that the Matterport Web Component is currently in public beta - interface and syntax are subject to change. ⚠️ Please email developer@matterport.com with any suggestions or questions.

The Matterport Web Component (NPM package name: @matterport/webcomponent) is a Web Component (custom HTML element) that encapsulates the Matterport experience in a single DOM element:

<!-- Create a full 3D viewer on your site -->
<matterport-viewer m="SxQL3iGyoDo"></matterport-viewer>

Read the quick installation instructions, check out advanced usage tips, or continue to the tutorial to learn more.

Tutorial

Prerequisites

• You should be familiar with the command line.
• You should have NPM or Yarn installed.
• Finally, you should obtain an SDK key.

Starting Your Project

The Web Component package will work with any framework (React, Vue, Svelte, etc) or vanilla JavaScript or TypeScript.

Let’s start a project using vanilla JS and Webpack. Tools like Vite can be useful if you’d like to skip some of the setup work, but for now we’ll stick with creating the project manually. (If you know how to create a project where you can npm install or yarn add dependencies, you can do so and skip ahead.)

Open the command line and navigate to the folder where you want your project. Then create a project folder and navigate into it. We’ll call our project and its folder mp-webcomponent:

mkdir mp-webcomponent
cd mp-webcomponent

Initialize a new NPM or Yarn project. (Choose one or the other, whichever you prefer - we will provide instructions for both in this tutorial.) You can accept the default values in all of the prompts.

# yarn
yarn init

# npm
npm init

Next, install Webpack and a few plugins:

# yarn
yarn add --dev webpack webpack-cli webpack-dev-server html-webpack-plugin

# npm
npm install --save-dev webpack webpack-cli webpack-dev-server html-webpack-plugin

And install Three:

# yarn
yarn add three@0.146

# npm
npm install three@0.146

Create a file called webpack.config.js at your project root and set it up by pasting the following content:

const HtmlWebpackPlugin = require('html-webpack-plugin');
const path = require('path');

module.exports = {
  entry: "./src/index.js",
  output: {
    path: path.resolve(__dirname, "./dist"),
    filename: "index_bundle.js",
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: path.resolve(__dirname, "./src/index.html"),
    }),
  ],
  devServer: {
    static: [path.resolve(__dirname, "static")],
  },
};

Add the following scripts property (or replace the existing one) at the top level of your package.json file:

"scripts": {
  "dev": "webpack serve --mode=development",
  "build": "webpack"
}

Finally, add a folder called src to the project root, and add a file called index.js and one called index.html inside src:

mkdir src
touch src/index.html
touch src/index.js
Your project folder should now look like this:

| node_modules
| package.json
| src/
|-- index.html
|-- index.js
| webpack.config.json

Your terminal should be in the mp-webcomponent directory

(Don’t worry if you see extra package-lock.json or yarn.lock files - those are generated for internal use by NPM and Yarn, respectively.)

Adding the Web Component

Next, we’ll add the Web Component:

# yarn
yarn add @matterport/webcomponent

# npm
npm install @matterport/webcomponent

And we’ll add the static assets:

# yarn
yarn matterport-assets static

# npm
npx matterport-assets static

Open index.js and import the Web Component by adding this line:

import '@matterport/webcomponent';

Then open index.html and add this line:

<matterport-viewer m="SxQL3iGyoDo"></matterport-viewer>

The Web Component wraps a custom web component that contains the 3D Matterport viewer; the m attribute sets the ID of the model you’d like to load. The value of m here is a sample space you can use for testing and dev.

Start your server:

# yarn
yarn dev

# npm
npm run dev

and navigate to localhost:8080. You should see a Matterport viewer and a sample space on your page.

Interacting with the Space

You can interact with the space by providing your SDK key to the application-key attribute (see here if you don’t have an SDK key yet):

<matterport-viewer m="SxQL3iGyoDo" application-key="YOUR_SDK_KEY"></matterport-viewer>

Once you’ve done that, the viewer will emit two events you can listen for:

1. mpSdkConnected - the SDK is connected and ready to use.
2. mpSdkPlaying - the SDK is connected and ready to use, and the camera is ready to start accepting commands (ie, any intro fly-in has completed and the camera has stopped moving).

Both events have the same call signature, so you can swap out mpSdkPlaying for mpSdkConnected if needed. In index.js:

const viewer = document.querySelector('matterport-viewer');
viewer.addEventListener('mpSdkPlaying', evt => {
  const mpSdk = evt.detail.mpSdk;
  mpSdk.Camera.rotate(90, 0);
})

An even easier route is using the sdkPromise/playingPromise properties provided by the component, which correspond with the mpSdkConnected event and the mpSdkPlaying event, respectively.

To use those properties, add the following to your index.js file:

const main = async () => {
  const mpSdk = await document.querySelector('matterport-viewer').playingPromise;
  mpSdk.Camera.rotate(90, 0);
}
main();

Note that if you’re using TypeScript you can set up querySelector to preserve strong typing:

const mpSdk = await document.querySelector<MatterportViewer>('matterport-viewer')!.playingPromise;

If you’ve added a working SDK key, you should see the model load, fly in, and turn to the right.

Next Steps

At this point, you can work with anything from any of the mpSdk namespaces, including Tags, Measurements, Scene objects, and more. Enjoy, and please reach out to developer@matterport.com with any questions or issues!

Iframe to Webcomponent Migration

You can follow the existing bundle steps exactly as written using the new webcomponent package, with one exception: you’ll download the zipped file by following these instructions:

1. Install npm on your machine if it isn’t already. (Run npm -v in your terminal to check if it is - if you see a number, you’re all set.)
2. Run npm view @matterport/webcomponent.
3. Download the linked .tarball file (for example, this link for version 0.1.1).
4. Move the built-bundle directory to your project, not bundle.

From there, follow these steps:

1. Add the dist directory from the .tgz you downloaded in the previous step to your project.
2. Add Three to your project: <script src="built-bundle/vendors/three/0.146.0/three.min.js"></script> (assuming you moved built-bundle to your project).
3. Add the webcomponent to your project: <script src="dist/matterport-viewer.umd.js"></script>
4. Change the iframe tag to a matterport-viewer tag. (You can leave the src attribute as-is on matterport-viewer).

That’s it! The webcomponent should now be running instead of the iframe.

Advanced Workflow

URL parameters/iframe migration

Any URL parameter can be added as an attribute to the <matterport-viewer> component. For example, to turn on quickstart (qs) and set MLS (mls) to option 2:

<matterport-viewer m="SxQL3iGyoDo" qs="1" mls="2"></matterport-viewer>

If you’re migrating from the old iframe-based workflow, you can also reuse your src attribute in the new viewer and preserve the same options:

<!-- You can turn this: -->
<iframe
  src="/bundle/showcase.html?m=22Ub5eknCVx&play=1&qs=1&log=0&applicationKey=PUT_APPLICATION_KEY_HERE">

<!-- into this, and keep the same functionality: -->
<matterport-viewer
  src="/bundle/showcase.html?m=22Ub5eknCVx&play=1&qs=1&log=0&applicationKey=PUT_APPLICATION_KEY_HERE">

Non-root static assets

You don’t have to put the static assets in the root of your static assets directory. For example, if you want to keep your Matterport assets in a folder called foo inside your static assets directory called public:

# yarn
yarn matterport-assets public/foo

# npm
npx matterport-assets public/foo

Then, in your matterport-viewer component, add the asset-base attribute:

<matterport-viewer asset-base="foo"></matterport-viewer>

This indicates that static assets for the viewer that would normally be served at / are instead served at /foo/.

.gitignore-ing static assets and copying at build time

The matterport-assets command copies >20mb of files to your static asset directory; this can be cumbersome to check into source control, especially since those static assets are downloaded each time you install @matterport/webcomponent.

You can make the process easier if you’re using a build process to generate your site. For this example, let’s assume you’re serving viewer assets from a subdirectory foo of your static assets directory public, like in the “Non-root static assets” section above.

1. When installing the viewer, run yarn matterport-assets public/foo (or npx matterport-assets public/foo) like you normally would.
2. Add public/foo to your .gitignore file.
3. Add the same command you used in step 1 (yarn matterport-assets public/foo or npx matterport-assets public/foo) to your postinstall script in package.json:

     "scripts": {
    ...
    "postinstall": "yarn matterport-assets public/foo",
    ...
     }
   

   This will automatically copy static assets to the correct location any time you yarn/npm install this project in the future.

4. Develop locally like you normally would.
5. When pushing to CI: this should normally take care of asset installation, since CI should install dependencies (and therefore run postinstall afterward) automatically. If needed, you can add the same command from step 1 to the CI’s build command (for example, yarn matterport-assets public/foo && yarn build).

React/Vue/Svelte/etc interoperability

Custom Web Components like this one are part of browsers’ built-in capability and all usable within popular frameworks like React, Vue, Svelte, Next, Nuxt, etc. If you’re using the web component in one of those frameworks, search use custom web component [framework name] to find steps for your specific environment.

Upgrading/Version pinning

To upgrade your project’s version of the package, run:

# yarn
yarn upgrade @matterport/webcomponent

# npm
npm upgrade @matterport/webcomponent

Then run the matterport-assets command to copy the latest version of the viewer assets:

# yarn
yarn matterport-assets YOUR_STATIC_ASSETS_DIR

# npm
npx matterport-assets YOUR_STATIC_ASSETS_DIR

If you’re committing static assets to source control, you’ll probably see some changes to those assets marked at this point. That’s expected - the assets you’re copying are specific to the version of the @matterport/webcomponent package you’ve installed.

(Note that this also means you can pin which version of the Matterport viewer you want on your page by leaving the package’s version as-is; you can also upgrade to a specific version of the viewer by installing a desired version of the package.)

OAuth/other connect options

You may be familiar with passing options to the SDK in the connect function:

MP_SDK.connect(
  myShowcaseWindow,
  { auth: 'abc' } // <-- these options
)

You can provide options to connect by adding attributes starting with connect- to your component. For example:

<matterport-viewer connect-auth="abc"></matterport-viewer>

This will match the JS above, and any future connect options will follow this same pattern automatically.

Adding on an Existing Frontend Project TL;DR

1. yarn add @matterport/webcomponent three
2. Run yarn matterport-assets YOUR_STATIC_ASSETS_DIR, replacing YOUR_STATIC_ASSETS_DIR with your static assets dir
3. import @matterport/webcomponent in your JS/TS
4. Add a <matterport-viewer> to your HTML. Add the m attribute with the SID of the model you want to use.
5. To use the SDK:
   1. Add the application-key attribute with the value set to your SDK key
   2. Either:
      1. Wait for the playingPromise:

            const viewer = document.querySelector('matterport-viewer');
            const mpSdk = await viewer.playingPromise;
         

      2. OR listen for the mpSdkPlaying event:

            const viewer = document.querySelector('matterport-viewer');
            viewer.addEventListener('mpSdkPlaying', async (evt) => {
          const mpSdk = evt.detail.mpSdk;
          /* do something with mpSdk... */
            });
         

Selecting Your Tools

You can use the Matterport Embed package or the Matterport Web Component to view spaces on your site. Generally, the Embed package provides a set-it-and-forget-it environment, while the Web Component is more powerful but requires some more manual maintenance.

Use the following grid to determine whether you need the Embed package or the Web Component:

Caveats

As mentioned earlier, ⚠️ the Matterport Web Component is currently in public beta - interface and syntax are subject to change. ⚠️ Please email developer@matterport.com with any suggestions or questions.

Some other caveats to note:

• The web component will load some assets and code (including fonts, scripts, images, polyfills, etc) into the global scope of your page. The Matterport team is currently working on reducing global content as much as possible; until then, note that some issues (like loading custom fonts, using a compatibility checker to detect outdated browsers, and using the webgl-memory WebGL extension) necessitate working in the global scope.