Download / Load / Scan

While running, Kivicube displays three kinds of status UI by default:

• asset download
• scene loading
• recognition scanning

The host page can either keep the default UI or take over with properties and events.

Download Progress

Hide the Default Download UI

await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  hideDownload: true,
});

Take Over Download Progress Yourself

iframe.addEventListener('downloadAssetProgress', (event) => {
  const progress = event.detail;
  updateProgressBar(progress);
});

Loading State

Hide the Default Loading UI

await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  hideLoading: true,
});

Take Over Loading Yourself

iframe.addEventListener('loadSceneStart', () => {
  showLoading();
});

iframe.addEventListener('loadSceneEnd', () => {
  hideLoading();
});

Scanning State

In Image AR and Basic AR/Gyroscope scenes, the default scan UI is shown until a target is recognized.

Hide the Default Scan UI

await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  hideScan: true,
});

Show Custom Scan Guidance from the Host Layer

iframe.addEventListener('loadSceneEnd', () => {
  showScanHint();
});

iframe.addEventListener('tracked', () => {
  hideScanHint();
});

iframe.addEventListener('lostTrack', () => {
  showScanHint();
});

Recommended Combinations

Light Customization

• keep the default download and loading UI
• customize only the scan copy

Moderate Customization

• hide download and loading UI
• use your own host-layer progress bar and landing page content
• keep scan-state visuals consistent with the host brand

Heavy Customization

• hide all default flow UI
• maintain a full host-layer state machine yourself
• drive every phase with events

Notes

Once you hide the default UI, the host page takes responsibility for:

• clearly telling users whether the app is downloading, loading, or waiting for recognition
• preventing the page from feeling frozen
• managing custom UI state correctly