Latest Version
SDK Bundle
SDK Release | 23.11.1_webgl-82-g7e8efde062 |
Last Updated | November 20, 2023 |
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:
- Iframe (standard method)
- Custom Web Component/NPM package (beta)
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
package.json
’s peerDependencies
field. You may try using a different version if you prefer, but only the listed version is supported.yarn add --dev @types/three
or npm install --save-dev @types/three
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
You may, but do not need to, check these files into source control - instead, you can include the yarn/npx matterport-assets your/static/folder command in your build script if you’re using a static site generator like Netlify. More on this workflow later.
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:
mpSdkConnected
- the SDK is connected and ready to use.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:
- 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.) - Run
npm view @matterport/webcomponent
. - Download the linked .tarball file (for example, this link for version 0.1.1).
- Move the
built-bundle
directory to your project, notbundle
.
From there, follow these steps:
- Add the
dist
directory from the .tgz you downloaded in the previous step to your project. - 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). - Add the webcomponent to your project:
<script src="dist/matterport-viewer.umd.js"></script>
- Change the
iframe
tag to amatterport-viewer
tag. (You can leave thesrc
attribute as-is onmatterport-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.
- When installing the viewer, run
yarn matterport-assets public/foo
(ornpx matterport-assets public/foo
) like you normally would. - Add
public/foo
to your.gitignore
file. - Add the same command you used in step 1 (
yarn matterport-assets public/foo
ornpx matterport-assets public/foo
) to yourpostinstall
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. - Develop locally like you normally would.
- 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
yarn add @matterport/webcomponent three
- Run
yarn matterport-assets YOUR_STATIC_ASSETS_DIR
, replacingYOUR_STATIC_ASSETS_DIR
with your static assets dir import @matterport/webcomponent
in your JS/TS- Add a
<matterport-viewer>
to your HTML. Add them
attribute with the SID of the model you want to use. - To use the SDK:
- Add the application-key attribute with the value set to your SDK key
- Either:
- Wait for the
playingPromise
:const viewer = document.querySelector('matterport-viewer'); const mpSdk = await viewer.playingPromise;
- 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... */ });
- Wait for the
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:
I want to… | Embed (yarn add @matterport/sdk ) |
Web Component (yarn add @matterport/webcomponent ) |
---|---|---|
…use the SDK to interact with a Matterport space | ✅ | ✅ |
…always automatically use the latest version of the Matterport viewer | ✅ | ❌ |
…pin the version of the Matterport viewer and be responsible for upgrades myself | ❌ | ✅ |
…add objects/lighting/textures to the scene | ❌ | ✅ |
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.