The Matterport 3D Showcase SDK is a javascript library for third-party developers to integrate Matterport with their web applications. Developers can deeply customize the 3D Showcase experience and build entire applications off of Matterport, enabling many exciting new use cases.

See full documentation for the SDK here.

Installation

⚠️ Make sure to obtain an SDK key before installing. ⚠️

Starter packages

See this repo for examples in several JS frameworks and vanilla JS.

Existing projects

You can also add the package to your existing project, or to a freshly-initialized npm/yarn project:

1. npm install @matterport/sdk or yarn add @matterport/sdk.
2. In your code:

import { setupSdk } from '@matterport/sdk'

const mpSdk = await setupSdk('YOUR_SDK_KEY')
// or, for a specific public space
const mpSdk = await setupSdk('YOUR_SDK_KEY',  { space: 'YOUR_SPACE_ID' })`

3. Use mpSdk to interact with your Matterport space (see documentation here). For example:

const mpSdk = await setupSdk('YOUR_SDK_KEY')

// commands
mpSdk.Tour.start()
// observables
mpSdk.Camera.pose.subscribe(pose => { /* ... */ })
// etc

Options

You can pass an object with SDK options as the second argument of setupSdk. Allowed properties and their defaults:

const options = {
  /**
   * Array of options to pass on SDK connection.
   * Anything from sdk.connect will work here.
   */
  connectOptions: [],

  /**
   * The element or selector that will attach the created iframe.
   * Defaults to document.body if not specified.
   * Ignored if the `iframe` option is provided.
   */
  container: undefined,

  /**
   * The domain to connect to. Defaults to `my.matterport.com`.
   */
  domain: 'my.matterport.com',

  /**
   * The element or selector to use as the iframe for space display.
   * Creates a new iframe if falsy. Default `undefined`.
   */
  iframe: undefined,

  /**
   * The options to pass to the iframe, as an object of
   * attribute keys and values.
   *
   * { width: '500px', height: '500px' }
   * creates: <iframe width="500px" height="500px">
   * ```
   */
  iframeAttributes: {},

  /**
   * The query params to include in the iframe's `src` URL. See 
   * https://support.matterport.com/s/article/URL-Parameters
   * for a full list.
   *
   * Do not specify the `m` param in these params - 
   * use the `space` option instead.
   *
   * ```
   * { qs: 1 }
   * creates: <iframe src="...&qs=1">
   * ```
   */
  iframeQueryParams: {},

  /**
   * Space ID. Defaults to an example if not specified.
   */
  space: 'SxQL3iGyoDo',
}

const mpSdk = await setupSdk('YOUR_SDK_KEY', options)

Typescript Support

Installation of the Matterport SDK NPM Package will automatically fetch the latest copy of our typescript definitions.

The Matterport SDK is actively maintained and updated, and over time your types may becoming outdated. Be sure to keep track of updates by visiting our change log. You can update the types with the latest definitions at any time by running:

yarn update-mpsdk-types
# If using npm, use `npx`:
npx update-mpsdk-types