Advanced Embed Options

This page is for web developers building a deeper integration — a hero section showing a single slowly-rotating room, a gallery of scenes, or a tour that reacts to the visitor's cursor. If you just want the tour on a page, Embedding Basics is all you need.

How it works

Add query parameters to the tour URL in your iframe's src:

<iframe
  src="https://your-tour-address/?mode=scene&scene=main-room&ui=none&autoRotate=1"
  width="100%"
  height="600"
  style="border: 0;"
  allow="fullscreen; gyroscope; accelerometer; xr-spatial-tracking"
></iframe>

We'll provide the scene slugs for your tour on request. They match the public scene value used in share links.

Parameters

Scene & interface

Input

Auto-rotate

Cursor-driven motion

For hero sections where the panorama subtly follows the visitor's mouse:

With cursor=parent, the embedding page reports its pointer via postMessage to the iframe:

const frame = document.querySelector("iframe");
const viewerOrigin = new URL(frame.src).origin;

document.addEventListener("mousemove", (event) => {
  frame.contentWindow.postMessage(
    {
      type: "realview:pointer",
      payload: {
        // Normalized to the range -1..1 across the page
        x: (event.clientX / window.innerWidth) * 2 - 1,
        y: (event.clientY / window.innerHeight) * 2 - 1,
        active: true,
      },
    },
    viewerOrigin
  );
});

Preload and navigate from your page

A scene gallery should keep one iframe alive and ask that viewer to prepare the next scene. This preserves its decoded image and GPU caches, then uses the same optimized transition path as the viewer's own navigation.

Wait for realview:ready, preload on pointer or keyboard intent, and navigate on activation:

<iframe
  id="tour"
  src="https://your-tour-address/?mode=scene&scene=main-room&ui=none&hotspots=hideAll"
  width="100%"
  height="600"
  style="border: 0;"
  allow="fullscreen; gyroscope; accelerometer; xr-spatial-tracking"
></iframe>

<button data-scene="main-room">Main room</button>
<button data-scene="suite">Suite</button>

<script>
  const frame = document.querySelector("#tour");
  const viewerOrigin = new URL(frame.src).origin;
  let viewerReady = false;

  window.addEventListener("message", (event) => {
    if (event.origin !== viewerOrigin || event.source !== frame.contentWindow) return;

    if (event.data?.type === "realview:ready") {
      viewerReady = true;
    }

    if (event.data?.type === "realview:scene-change") {
      document.querySelectorAll("[data-scene]").forEach((button) => {
        button.setAttribute("aria-pressed", String(
          button.dataset.scene === event.data.payload.scene
        ));
      });
    }
  });

  function send(type, scene) {
    if (!viewerReady) return;
    frame.contentWindow.postMessage({ type, payload: { scene } }, viewerOrigin);
  }

  document.querySelectorAll("[data-scene]").forEach((button) => {
    button.addEventListener("pointerenter", () => {
      send("realview:scene-preload", button.dataset.scene);
    });
    button.addEventListener("focus", () => {
      send("realview:scene-preload", button.dataset.scene);
    });
    button.addEventListener("click", () => {
      send("realview:scene-navigate", button.dataset.scene);
    });
  });
</script>

Both commands accept a public scene slug, never an internal scene ID. Commands are scoped to the tour already loaded in the iframe, so changing to a scene from another tour still requires a new iframe URL. Invalid slugs and commands sent before authorization are ignored safely.

The viewer sends these lifecycle messages back to the embedding page:

{ type: "realview:ready", payload: { apiVersion: 1, sceneId, scene } }
{ type: "realview:scene-change", payload: { sceneId, scene } }

scene is the public slug, or null for an older scene that has no public slug. realview:scene-change also fires when navigation commits inside a full-tour viewer, so the surrounding page can keep its buttons in sync.

Example recipes

Ambient hero background — one scene, no interface, slow rotation, no interaction:

?mode=scene&scene=main-room&ui=none&hotspots=hideAll&drag=0&zoom=0&keyboard=0&autoRotate=1&autoRotateSpeed=0.5&autoRotateIdleDelay=0

Cursor-follow hero — the room sways gently with the visitor's mouse:

?mode=scene&scene=main-room&ui=none&hotspots=hideAll&drag=0&zoom=0&cursor=parent&cursorMaxYaw=8&cursorMaxPitch=4

Scene gallery — one retained iframe controlled by the preload/navigation messages above:

?mode=scene&scene=main-room&ui=none&hotspots=hideAll