Viewer SDK events¶

This is the complete stable event surface of Viewer SDK v3.0.0. Subscribe with viewer.on(), remove a listener with viewer.off(), or subscribe once with viewer.once().

Event	Payload	When it fires
`runtime-ready`	`{ viewer }`	The viewer runtime has initialized. This occurs before `mount()` resolves.
`load-start`	`{ filename, raw }`	A scene begins loading.
`load-progress`	`{ percentage, raw }`	Scene loading advances; `percentage` is numeric.
`scene-ready`	`{ raw }`	The scene has finished loading and is interactive.
`error`	`{ error, raw }`	A scene load fails. `error` is a `WebexViewerError` with a stable `code`.
`event`	`{ type, d0, d1, d2 }`	Any viewer message, exposed as a general event envelope.

Only the names in this table are part of the stable named-event contract. The general event subscription is useful for diagnostics and integrations that need messages not represented by a named lifecycle event.

Listening for events¶

function reportProgress({ percentage }) {
  progress.value = percentage;
}

viewer.on('load-progress', reportProgress);
viewer.once('scene-ready', () => {
  controls.disabled = false;
});

await viewer.load('./product.webex');
viewer.off('load-progress', reportProgress);

on(), off(), and once() return the viewer, so calls can be chained.

Initial scene loading¶

When scene is passed to WebexViewer.mount(), the mount promise resolves only after that scene is ready. Registering listeners on the returned viewer is therefore suitable for later load() calls, not for the initial load.

Use onEvent when mounting if you need a general event feed during initialization:

const viewer = await WebexViewer.mount({
  container: '#viewer',
  apiKey: 'ak_xxxxxxxxxxxxxxxx',
  scene: './product.webex',
  onEvent(event) {
    console.debug(event.type, event.d0, event.d1, event.d2);
  }
});

Errors and asynchronous operations¶

The named error event reports scene-loading failure. Operations such as capture(), getProperty(), mergePart(), removePart(), and clearParts() report failure by rejecting their returned promises:

try {
  await viewer.mergePart('head', './parts/head.webex');
} catch (error) {
  console.error(error.code, error.message);
}

Use the promise as the authoritative completion signal for those operations.