Open and Close a Scene / Collection

For full function signatures, see:

• Plugin API / openKivicubeScene
• Plugin API / openKivicubeCollection

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:

<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

<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:

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:

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

Or open one manually:

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:

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

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:

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

Recommended Wrapper

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

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);
}