Embedding SpatialWork

The shortest version that works

Two things are always required: the iframe, and a listener. The scene will render from the iframe alone — but it can only drive your page if your page is listening. This is exactly what the Embed button copies.

<iframe id="sw" width="100%" height="600" style="border:0" allow="fullscreen"></iframe>
<script>
const SW_ORIGIN = 'https://spatialwork.hiverlab.com';   // no trailing slash
const sw = document.getElementById('sw');

window.addEventListener('message', (e) => {
  // Only the scene in THIS iframe, from the viewer's exact origin.
  if (e.origin !== SW_ORIGIN || e.source !== sw.contentWindow) return;
  if (e.data?.source !== 'spatialwork') return;
  const { type, payload } = e.data;
  if (type === 'ready') console.log('scene ready', payload.objects);      // before assets finish
  if (type === 'loaded') console.log('scene loaded', payload.objects);    // everything on screen
  if (type === 'object-click') console.log('clicked', payload);           // { id, name, data, fromHost, … }
  if (type === 'version') console.log('now showing', payload);            // after a switch; the frame reloaded
});

// Set src only after the listener exists, so no message can arrive before you listen.
sw.src = 'https://spatialwork.hiverlab.com/p/YOUR_CODE';

// The other direction: click an object from your page. It highlights, the camera
// flies to it, and the same object-click comes back with fromHost: true.
function selectInScene(q) {   // { id } | { name } | { data: { asset: 'PUMP-01' } }
  sw.contentWindow.postMessage({ source: 'spatialwork-host', type: 'select', payload: q }, SW_ORIGIN);
}
// Switch version (ids and names are in ready.versions). The frame reloads.
function showVersion(q) {     // { id } | { name: 'Level 5' }
  sw.contentWindow.postMessage({ source: 'spatialwork-host', type: 'goto-version', payload: q }, SW_ORIGIN);
}
</script>

How the channel works

Messages you receive

Every message from the viewer carries source: 'spatialwork'. Check that, and check e.origin, before trusting anything.

The object-click payload in full

Where data comes from

Key your dashboard on data, not on name: the name is the scene author's label, while data holds your own identifiers, so a rename or a re-export upstream will not silently break the integration. It is filled from two places.

• Binding keys use your API's own field names. Every field=='value' condition in the filter is included, and the key is identical to the one your system already uses. If the filter lists several values for one field (@.assetId=='99959' || @.assetId=='99960'), they arrive comma-joined: "99959,99960".
• Only a binding that targets that one object counts. A binding over a whole group, or over several objects, describes all of them and says nothing about any single one, so it adds nothing.
• Values are always strings. If a tag and a binding give the same key, the tag wins. That gives the author a way to correct a key without touching the binding.
• The same data appears for every object in ready.objects and loaded.objects, so you can map your records to the scene before anyone clicks.

The ready payload in full

Lifecycle and ordering

Four behaviours worth designing around, because they are deliberate rather than incidental.

1. ready fires before the scene finishes loading

The bridge opens before assets are requested, so one slow model can never stop your page from hearing ready. The consequence: when ready arrives the object list is complete and addressable, but the geometry behind it may still be streaming in. A select sent immediately will resolve the object and post its echo; the camera flight and the highlight box, which need real bounds, settle once that object has loaded. If you need the scene fully on screen first, wait for loaded, which follows once every asset is in. If your listener connects late, connect brings back ready, and loaded too when loading has already finished.

2. There is no handshake

The viewer does not wait to be greeted — it posts ready as soon as it can. If your listener attaches late and misses it, send connect and a fresh ready comes back. That is the only reason connect exists; you never need it if your listener is registered before the iframe loads.

3. Switching version reloads the frame

A version is its own page: the picker and goto-version both load the same link with a different ?v=, so the iframe reloads and the app boots again. After the reload you get a second ready, whose version field names the version now showing, immediately followed by a version message whose fromHost says whether you asked for it or a person picked it. Treat it as "the frame reloaded, re-sync everything": your cached object ids from the previous ready belong to the old version and may not exist in the new one. A plain browser refresh sends ready but no version, because nothing was switched.

To open a specific version from the start, load the frame as usual and send goto-version once the first ready arrives.

4. Viewpoint and version messages report both directions

A viewpoint message is sent when anyone moves the camera to a saved viewpoint — your goto-viewpoint or reset-camera command (fromHost: true), or a person clicking the viewpoint panel or pressing a number key (fromHost: false). That lets a dashboard keep a "current view" indicator honest instead of only tracking the jumps it caused itself. Camera flights that are not saved viewpoints — the ones focus and select perform — deliberately stay silent, because they do not correspond to anything in your viewpoint list.

Messages you can send

Post these to the iframe's contentWindow, with the viewer's origin as the target — never '*'.

How select finds the object

The three payload shapes are tried in a fixed order, and the first that matches wins:

All keys in a data query must match (values compare as strings), and the first object in scene order wins if several qualify. An empty { data: {} } deliberately matches nothing rather than selecting an arbitrary object. Anything unmatched comes back as select-miss carrying your original query, so a broken key is visible in the console instead of failing silently.

function focusInScene(objectId) {
  document.getElementById('sw').contentWindow.postMessage(
    { source: 'spatialwork-host', type: 'focus', payload: { id: objectId } },
    'https://spatialwork.hiverlab.com'
  );
}

A complete two-way example

Clicking in 3D selects a row in your table; clicking a row clicks the object in 3D — it highlights, the camera flies to it, and the same object-click comes back so both directions run through one handler.

const VIEWER = 'https://spatialwork.hiverlab.com';
const frame  = document.getElementById('sw');
const byName = new Map();     // name → your record

window.addEventListener('message', (e) => {
  if (e.origin !== VIEWER || e.data?.source !== 'spatialwork') return;
  const { type, payload } = e.data;

  if (type === 'ready') {
    // Fires on first load AND again after a version switch (which reloads the
    // frame). Rebuild rather than merge: ids belong to the version that sent them.
    console.log(`${payload.project} · ${payload.version?.name}: ${payload.objectCount} objects`);
    byName.clear();
    // The scene tells you what is in it, so your rows can be wired up front —
    // no need to wait for someone to click an object to learn its id.
    for (const o of payload.objects) byName.set(o.data?.asset || o.name, o);
    buildViewpointButtons(payload.viewpoints);
  }

  if (type === 'viewpoint') {
    // Sent for your own goto-viewpoint (fromHost: true) and for a person picking
    // one in the panel (fromHost: false) — so this stays correct either way.
    markCurrentView(payload.index);
  }

  if (type === 'object-click') {
    const key = payload.data?.asset || payload.name;   // prefer your own key
    highlightRow(key);
    // payload.fromHost is true when YOU asked for this click. Guard the work you
    // have already done, or ignore the flag entirely and let one path do both.
    if (!payload.fromHost) loadDetails(key);
  }

  if (type === 'version') {
    // The frame reloaded onto another version (your goto-version, or a person's pick).
    // ready.objects above has already been rebuilt; just reflect the choice.
    markCurrentVersion(payload.id);
  }

  if (type === 'select-miss') console.warn('no such object', payload.query);
  if (type === 'version-miss') console.warn('no such version', payload.query);
});

// your version dropdown → the scene
function onVersionPick(versionId) {
  frame.contentWindow.postMessage(
    { source: 'spatialwork-host', type: 'goto-version', payload: { id: versionId } },
    VIEWER
  );
}

// your table → the scene
function onRowClick(record) {
  frame.contentWindow.postMessage(
    {
      source: 'spatialwork-host',
      type: 'select',
      // Any one of these addresses the object: your own tag key is the most
      // durable, since it survives a rename in the scene.
      payload: { data: { asset: record.assetTag } },
      // payload: { id: record.sceneObjectId }
      // payload: { name: 'Pump A' }
    },
    VIEWER
  );
}

function buildViewpointButtons(viewpoints) {
  for (const vp of viewpoints) {
    const b = document.createElement('button');
    b.textContent = vp.name;
    b.onclick = () => frame.contentWindow.postMessage(
      { source: 'spatialwork-host', type: 'goto-viewpoint', payload: { index: vp.index } },
      VIEWER
    );
    document.getElementById('views').appendChild(b);
  }
}

Before you go live

Troubleshooting