Kivicube Docs

English

简体中文

Appearance

Open and Close a Scene / Collection ​

For full function signatures, see:

Open ​

Scene ​

There are two ways to open a scene: automatically or manually.

Automatic Open ​

If the page contains this structure, the plugin script opens it automatically:

html
<script src="https://www.kivicube.com/lib/iframe-plugin.js"></script>
<iframe id="kivicubeScene" scene-id="7A43keFojH0v98xvFP2w52aF8Y67Zbb5"></iframe>

Automatic opening requires:

  • iframe.id === "kivicubeScene"
  • a valid scene-id
  • the iframe already exists before DOMContentLoaded fires

Manual Open ​

html
<script src="https://www.kivicube.com/lib/iframe-plugin.js"></script>

<iframe id="sceneHost"></iframe>

<script>
  const iframe = document.getElementById('sceneHost');

  kivicubeIframePlugin.openKivicubeScene(iframe, {
    sceneId: '7A43keFojH0v98xvFP2w52aF8Y67Zbb5',
    hideLogo: true,
    hideTitle: true,
    cameraPosition: 'back',
  });
</script>

Characteristics of openKivicubeScene():

  • the first argument must be an HTMLIFrameElement
  • the second argument is a props object and overrides same-name attributes already written on the iframe
  • after execution, the plugin automatically fills in iframe.id, iframe.allow, and iframe.src
  • the return value is a Promise whose result contains { id, allow, src }

Only Get the Assembled URL ​

There is also a third parameter, modifyIframe = true. If you pass false, you can get the generated src and allow without immediately writing them back to the iframe element:

js
const result = await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId: '7A43keFojH0v98xvFP2w52aF8Y67Zbb5',
}, false);

console.log(result.src, result.allow);

This is better suited to debugging or custom wrappers such as Vue / React components. For normal integrations, the default behavior is usually fine.

Collection ​

Collections work the same way as scenes. You only need to switch to the collection-specific API and identifier:

html
<iframe id="kivicubeCollection" collection-id="b46rfc"></iframe>

Or open one manually:

js
await kivicubeIframePlugin.openKivicubeCollection(iframe, {
  collectionId: 'b46rfc',
  hideLogo: true,
  hideGyroscopePermission: true,
});

The main differences are:

  • collection IDs are 6 characters long
  • collections support hideGyroscopePermission, while scenes do not

What to Do After Opening ​

In most cases, you should listen for the ready event on the iframe:

js
iframe.addEventListener('ready', (event) => {
  console.log(event.detail);
});

For scenes, event.detail.api gives you the advanced scene API.

For collections, event.detail.api also gives you an advanced API, but its interface differs from the scene version.

Close ​

Scene ​

The recommended pattern is:

  1. switch the iframe to a blank page, especially if you will open another scene later
  2. call the destroy method to clean up internal resources
js
iframe.src = 'https://www.kivicube.com/lib/empty.html';
kivicubeIframePlugin.destroyKivicubeScene(iframe);

If your flow removes the iframe node entirely, that is fine too, but manually calling destroyKivicubeScene() on the host side is still required.

Collection ​

Collections follow the same pattern:

js
iframe.src = 'https://www.kivicube.com/lib/empty.html';
kivicubeIframePlugin.destroyKivicubeCollection(iframe);

In real projects, it is usually best to wrap "open" and "close" into two functions instead of repeating the same code in multiple places:

js
export async function openScene(iframe, sceneId) {
  return kivicubeIframePlugin.openKivicubeScene(iframe, { sceneId });
}

export function closeScene(iframe) {
  iframe.src = 'https://www.kivicube.com/lib/empty.html';
  kivicubeIframePlugin.destroyKivicubeScene(iframe);
}