Latest Version

SDK Bundle

SDK Release 24.12.3_webgl-944-ge03b07c22c
Last Updated Dec 18, 2024

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: Dec 18, 2024
See the change log

Iframe Method

Download the latest SDK Bundle package

https://static.matterport.com/showcase-sdk/bundle/24.12.3_webgl-944-ge03b07c22c/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]',
});

SDK Web Component

Web component documentation has moved to its own page.