Kivicube Docs

English

简体中文

Appearance

Plugin API ​

This page describes the global plugin interfaces called directly from the host page.

Global Object ​

After you include:

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

the host page can use the global object directly:

js
window.kivicubeIframePlugin

A typical call looks like:

js
kivicubeIframePlugin.openKivicubeScene(...)

Open a Scene ​

ts
openKivicubeScene(
  iframe: HTMLIFrameElement,
  props?: SceneOpenProps,
  modifyIframe?: boolean,
): Promise<{
  id: string;
  allow: string;
  src: string;
}>

Parameters ​

iframe ​

The iframe DOM element that hosts Kivicube content.

props ​

Scene opening parameters. See SceneOpenProps below.

modifyIframe ​

Whether to immediately write the generated id, allow, and src back to the iframe.

  • default: true
  • if false, the method only returns the computed result and does not modify the DOM, which is useful for Vue / React wrappers

Return Value ​

ts
interface OpenResult {
  id: string;
  allow: string;
  src: string;
}

Destroy a Scene ​

ts
destroyKivicubeScene(iframe: HTMLIFrameElement): void

This cleans up the internal resources associated with the current iframe. It is commonly used together with switching iframe.src to a blank page.

Important: if you switch between multiple scenes on the same page, always call destroyKivicubeScene() when closing the previous scene.

Open a Collection ​

ts
openKivicubeCollection(
  iframe: HTMLIFrameElement,
  props?: CollectionOpenProps,
  modifyIframe?: boolean,
): Promise<{
  id: string;
  allow: string;
  src: string;
}>

This is essentially the same as openKivicubeScene(), except that props uses the collection version.

Destroy a Collection ​

ts
destroyKivicubeCollection(iframe: HTMLIFrameElement): void

Property Objects ​

SceneOpenProps ​

ts
interface SceneOpenProps {
  sceneId: string;
  hideLogo?: boolean;
  hideTitle?: boolean;
  hideDownload?: boolean;
  cameraPosition?: 'front' | 'back';
  hideLoading?: boolean;
  hideScan?: boolean;
  hideTakePhoto?: boolean;
  hidePhotoPreview?: boolean;
  hideBackground?: boolean;
  hidePcGuide?: boolean;
  guideUrl?: string;
  hideStart?: boolean;
  disableOpenUrl?: boolean;
}

CollectionOpenProps ​

ts
interface CollectionOpenProps extends Omit<SceneOpenProps, 'sceneId'> {
  collectionId: string;
  hideBackToScan?: boolean;
  hideGyroscopePermission?: boolean;
}

How HTML Attributes Are Read ​

The plugin reads supported attributes from the iframe and accepts all of the following:

  • kebab-case: hide-logo
  • camelCase: hideLogo
  • data attributes: data-hide-logo

When you call openKivicubeScene() or openKivicubeCollection(), the JavaScript props object overrides same-name attributes that already exist in HTML.

Automatic Opening Rules ​

Scenes ​

If the page contains:

html
<iframe id="kivicubeScene" scene-id="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"></iframe>

and the element already exists before DOMContentLoaded, the plugin automatically calls openKivicubeScene().

Collections ​

If the page contains:

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

the plugin automatically calls openKivicubeCollection().

Automatically Injected allow Permissions ​

The plugin automatically writes the required permission string:

text
xr-spatial-tracking;camera;microphone;autoplay;fullscreen;gyroscope;accelerometer