Developer Documentation

Everything you need to integrate the 3D viewer into your website.

Quick Start

Load the viewer script:

<script src="https://cdn.3d-lion.com/glb-viewer-loader.iife.js"></script>

Place the viewer on your page:

<glb-viewer
  api-key="pk_your_api_key_here"
  model-url="https://yoursite.com/models/product.glb"
  style="width: 100%; height: 600px;">
</glb-viewer>

That's it — your 3D viewer is live.

Web Component Attributes

Attribute		Description
`api-key`	Required	Your API key (pk_...)
`model-url`	Required	URL to your .glb model file
`api-url`	Optional	API endpoint (default: production)
`enable-shadows`	Optional	Enable shadow rendering
`enable-ssao`	Optional	Enable ambient occlusion
`auto-rotate`	Optional	Auto-rotate the model
`tour-autoplay`	Optional	Auto-play the camera tour on load
`camera-mode`	Optional	orbit or free (default: orbit)

Events

Listen for viewer lifecycle events using standard addEventListener.

const viewer = document.querySelector('glb-viewer');

// Viewer initialized, modules loaded
viewer.addEventListener('viewer:ready', (e) => {
  console.log('Ready:', e.detail.availableModules);
});

// 3D model loaded
viewer.addEventListener('model:loaded', (e) => {
  console.log('Model loaded:', e.detail.modelUrl);
});

// Error (invalid key, domain forbidden, etc.)
viewer.addEventListener('viewer:error', (e) => {
  console.error('Error:', e.detail.message);
});

Iframe postMessage API

When embedding the viewer in an iframe, use postMessage to communicate across origins. The viewer broadcasts a ready message automatically on init — no polling needed.

Receiving ready state

window.addEventListener('message', (event) => {
  const msg = event.data;
  if (msg?.type !== 'glb-viewer:ready') return;

  console.log('Zones:', msg.zones);
  console.log('Tour:', msg.tour);
  console.log('Animations:', msg.animations);
});

Sending commands

Colors

const iframe = document.querySelector('iframe');

iframe.contentWindow.postMessage(
  { type: 'glb-viewer:setColor', zoneId: 'body', hex: '#ff0000' }, '*'
);

iframe.contentWindow.postMessage(
  { type: 'glb-viewer:reset' }, '*'
);

Tour

iframe.contentWindow.postMessage({ type: 'glb-viewer:tour:play' }, '*');
iframe.contentWindow.postMessage({ type: 'glb-viewer:tour:stop' }, '*');
iframe.contentWindow.postMessage({ type: 'glb-viewer:tour:togglePause' }, '*');

// Request status → responds with:
// { type: 'glb-viewer:tour:status', isPlaying, isPaused, hasWaypoints }
iframe.contentWindow.postMessage({ type: 'glb-viewer:tour:status' }, '*');

Animations

// List all animations
iframe.contentWindow.postMessage({ type: 'glb-viewer:animations:list' }, '*');
// → { type: 'glb-viewer:animations:list', entries: [{ id, label }] }

iframe.contentWindow.postMessage({ type: 'glb-viewer:animations:play', id: 'open-door' }, '*');
iframe.contentWindow.postMessage({ type: 'glb-viewer:animations:stop', id: 'open-door' }, '*');
iframe.contentWindow.postMessage({ type: 'glb-viewer:animations:playAllLoop' }, '*');
iframe.contentWindow.postMessage({ type: 'glb-viewer:animations:stopAll' }, '*');

Camera

iframe.contentWindow.postMessage(
  { type: 'glb-viewer:camera:setPosition', x: 0, y: 2, z: 5 }, '*'
);

iframe.contentWindow.postMessage(
  { type: 'glb-viewer:camera:setTarget', x: 0, y: 1, z: 0 }, '*'
);

iframe.contentWindow.postMessage(
  { type: 'glb-viewer:camera:setAutoRotate', enabled: true }, '*'
);

iframe.contentWindow.postMessage(
  { type: 'glb-viewer:camera:setMode', mode: 'orbit' }, '*'
);