Skip to content

Migrating from v1.0 to v1.1

v1.1 is fully backward compatible. Your existing code continues to work unchanged. This guide covers adopting the new create() API.

What Changed

v1.0 v1.1
Initialization window.__XRGALLERY_CONFIG__ global XRGallery.create() function
Element targeting Hardcoded #renderCanvas Any CSS selector or DOM element
Cloud tours Not supported via npm package sceneId parameter fetches from cloud
Lifecycle No cleanup API viewer.dispose() / viewer.isDisposed()
Framework support Manual canvas setup Works with React refs, Vue refs, etc.
TypeScript Basic types Full type tree for all config objects

Before / After

Self-Hosted Tour

<script>
  window.__XRGALLERY_CONFIG__ = {
    experience: { title: "My Tour" },
    stages: [
      {
        id: "main",
        name: "Main",
        skybox: { type: "image", url: "/pano.jpg" }
      }
    ]
  };
</script>
<script src="viewer-bundle.iife.js"></script>

<div id="app"></div>
<script src="viewer-bundle.iife.js"></script>
<script>
  (async () => {
    const viewer = await XRGallery.create({
      element: '#app',
      config: {
        experience: { title: "My Tour" },
        stages: [
          {
            id: "main",
            name: "Main",
            skybox: { type: "image", url: "/pano.jpg" }
          }
        ]
      }
    });
  })();
</script>

Cloud Tour (New in v1.1)

<div id="app"></div>
<script src="viewer-bundle.iife.js"></script>
<script>
  (async () => {
    const viewer = await XRGallery.create({
      element: '#app',
      sceneId: 'YOUR_SCENE_ID'
    });
  })();
</script>

This was not possible in v1.0 without manually setting up Firebase config.

React Component

// Required manual iframe embed or complex script loading
function VRViewer({ sequenceId }) {
  return (
    <iframe
      src={`https://xrgallery.online/viewer/${sequenceId}`}
      width="100%"
      height="600"
      allow="xr-spatial-tracking; fullscreen; autoplay"
    />
  );
}

function VRViewer({ sceneId }: { sceneId: string }) {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const v = XRGallery.create({ element: ref.current, sceneId });
    return () => { v.then(v => v.dispose()); };
  }, [sceneId]);

  return <div ref={ref} style={{ width: '100%', height: '100%' }} />;
}

Step-by-Step Migration

1. Update the Package

npm install @xrgallery/viewer@latest

2. Replace the Global Config

Remove window.__XRGALLERY_CONFIG__ and use create() instead.

Find: 

window.__XRGALLERY_CONFIG__ = { ... };

Replace with: 

const viewer = await XRGallery.create({
  element: '#app',  // or your container
  config: { ... }   // same config object
});

3. Add a Container Element

The v1.0 approach required a <canvas id="renderCanvas"> in your HTML. With create(), you just need a container <div>:

<!-- v1.0: needed this in your HTML -->
<canvas id="renderCanvas"></canvas>

<!-- v1.1: just a container div, canvas is created automatically -->
<div id="app" style="width: 100%; height: 100vh;"></div>

// Store the viewer instance
const viewer = await XRGallery.create({ ... });

// Clean up when done (SPA navigation, component unmount, etc.)
viewer.dispose();

No Breaking Changes

Everything from v1.0 still works:

  • window.__XRGALLERY_CONFIG__ auto-initialization
  • window.__XRGALLERY_OPTIONS__ (viewer.html)
  • XRGallery.init() low-level API
  • All config options and hotspot types
  • Canvas lookup by #renderCanvas

You can migrate incrementally.