Viewer Embed with the SDK

The fastest way to render a Moshpit scene on any website. The SDK creates the iframe, mints a session, refreshes the token automatically, and gives you a clean event/command API.

Minimal example

HTML

<div id="moshpit-viewer" style="height: 600px"></div>
 
<script src="https://moshpit.studio/moshpit-embed.js"></script>
<script>
  const viewer = Moshpit.viewer('#moshpit-viewer', {
    publicKey: 'mpk_PUBLIC_KEY',
    sessionEndpoint: '/api/moshpit/viewer-session',
    splatId: 'YOUR_SPLAT_ID',
  });
 
  viewer.on('ready', () => console.log('viewer ready'));
  viewer.on('viewTracked', (event) => {
    console.log('tracked', event.viewCount, event.isNewView);
  });
</script>

The SDK calls sessionEndpoint (a route on your server) to get a session token, then loads the hosted viewer. See Quickstart for the matching backend code.

Sizing and layout

The default mount fills its container and locks to a 16:9 aspect ratio:

JavaScript

Moshpit.viewer('#moshpit-viewer', {
  publicKey: 'mpk_...',
  sessionEndpoint: '/api/moshpit/viewer-session',
  splatId: '...',
  responsive: true, // default
  aspectRatio: '16 / 9', // default
});

For a fixed-size embed, set responsive: false and pass width / height:

JavaScript

Moshpit.viewer('#moshpit-viewer', {
  publicKey: 'mpk_...',
  sessionEndpoint: '/api/moshpit/viewer-session',
  splatId: '...',
  responsive: false,
  width: 960,
  height: 540,
});

Other style options: borderRadius, background, loading, referrerPolicy, title. See SDK Options for the full reference.

referrerPolicy controls the request from your page to the Viewer Embed. The hosted viewer uses no-referrer for its own Scene-file and API requests, so its session-bearing URL and Moshpit origin are not forwarded to the asset CDN.

React-style session callback

If you don't want to expose a sessionEndpoint, pass a getSessionToken callback instead:

JavaScript

Moshpit.viewer('#moshpit-viewer', {
  publicKey: 'mpk_...',
  splatId: '...',
  getSessionToken: async ({ publicKey, splatId }) => {
    const res = await fetch('/api/moshpit/viewer-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ publicKey, splatId }),
    });
    return res.json(); // { sessionToken, expiresAt }
  },
});

The callback runs once on mount and again whenever the SDK needs a fresh token (about 60 seconds before the current one expires).

Event handling

The viewer fires events as the user interacts with it:

JavaScript

viewer.on('ready', () => {
  // The first frame has rendered
});
 
viewer.on('viewTracked', ({ viewCount, isNewView }) => {
  // Moshpit just registered a view for analytics
});
 
viewer.on('fullscreenChanged', ({ fullscreen }) => {
  // The user entered or exited fullscreen
});
 
viewer.on('error', ({ message }) => {
  // Something went wrong inside the iframe
});

The full list lives on Viewer Events. Every .on(...) call returns an unsubscribe function.

Programmatic control

Drive the viewer from your page UI:

JavaScript

viewer.play();
viewer.pause();
viewer.mute();
viewer.unmute();
viewer.fullscreen();
viewer.setQuality('high');
viewer.goToAnnotation(2);

See Viewer Commands for parameter shapes.

Tear down

When the embed is no longer needed (single-page-app navigation, modal close, etc.), call destroy(). It removes the iframe, clears refresh timers, and unsubscribes all event listeners.

JavaScript

viewer.destroy();

What's next

Viewer → Plain Iframe — when you don't want the SDK.
Viewer → Next.js Integration — App Router and Pages Router.
Viewer Events and Viewer Commands — full surface.

External Users

Plain Iframe