Quick integration for Web AR Plugin

Showcase

Before integrating the plugin, you should first become familiar with creating AR Scenes or Bundle on the Kivicube platform.
If you need to remove the watermark or Splash screen, please contact our sales team to purchase Kivicube Pro / Enterprise.
If you need to use plugin-level properties and events, please contact our sales team to purchase plugin domain authorization (domain authorization can be migrated if needed).

Creating Scene or Collection

Supported Scene Types

AR Scenes
- Image AR
- Cloud Recognition / Gyroscope
3D Scenes
- Interactive 3D

Supported Collection Types

Image AR
Cloud Recognition / Gyroscope

Plugin Integration

Environment Requirement

WARNING

Pages that embed the plugin using an iframe (your custom H5 page) must run over HTTPS, or be accessed via http://localhost.

Otherwise, the iframe will not be able to access the device camera, and you may see errors such as “Supported only on iOS 11 or above.”

We do not recommend testing in a local development environment using LAN IPs such as 192.168.x.x, 172.16.x.x, or 10.x.x.x, unless you know how to properly configure HTTPS and ensure mobile devices can access it.

For reliable testing, we recommend deploying to an online environment with HTTPS enabled.

Importing Kivicube Library Code

html

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

Configuring iframe Tag

html

<style type="text/css">
  iframe#kivicubeScene,
  iframe#kivicubeCollection {
    /* Set width and height as needed */
    width: 100vw;
    height: calc(100vw * (4 / 3));

    /* Remove the browser’s default iframe border */
    border: none;
  }
</style>

<!-- Embed a Scene -->
<iframe id="kivicubeScene" scene-id="n5KxG0svcgNyZof1aWz2kGl6oHNh2JRl"></iframe>

<!-- Embed a Collection -->
<iframe id="kivicubeCollection" collection-id="b46rfc"></iframe>

Integrating Kivicube Scene

Automatically Opening a Scene

When you add an iframe with the ID kivicubeScene and specify a scene-id attribute, the imported library will automatically open the corresponding Scene (as shown in the code example above).

Opening a Scene via API

If the iframe does not use the ID kivicubeScene, or if no scene-id attribute is provided, the developer must manually open the Scene using the API.

javascript

// The global variable `kivicubeIframePlugin` is provided by the imported Kivicube library.
kivicubeIframePlugin.openKivicubeScene(document.querySelector("iframe"), {
  sceneId: "rDM7kXvo1UJKHnQUR46s7neoCSutDul9",
  hideLogo: true,        // Whether to hide the homepage logo. Default: false
  hideTitle: false,      // Whether to hide the homepage title. Default: false
  hideDownload: false,   // Whether to hide the download progress bar. Default: false
  cameraPosition: "back",// Camera direction: front or back. Default: back
  hideLoading: true,     // Whether to hide the loading indicator. Default: false
  hideScan: false,       // Whether to hide the scan UI and instructional text. Default: false
  hideTakePhoto: false,  // Whether to hide the photo button. Default: false
  hideBackground: true,  // Whether to hide the scene background. Default: false (only for Web 3D scenes)
});

Closing a scene

You can close a Scene by directly removing the iframe element (removing it from the DOM and clearing all references), or by changing its src to another URL, or setting it to "about:blank".

Any of these approaches will close the Scene.

However, regardless of which method you choose, you must also call the API to notify the Kivicube library that the Scene has been closed; otherwise, memory leaks may occur.

javascript

const iframe = document.querySelector("iframe");

// Method 1: Clear the iframe content.
// Note: This method does NOT work in iOS WeChat. Use Method 2 instead.
iframe.src = "about:blank";

// Method 2: Load another URL, such as the official empty page:
iframe.src = "https://www.kivicube.com/lib/empty.html";

// Method 3: Remove the iframe from the DOM.
iframe.parentNode.removeChild(iframe);

// IMPORTANT: No matter which method you use, you MUST call the destroy API.
kivicubeIframePlugin.destroyKivicubeScene(iframe);

Supported Properties

Scene ID

sceneId

Obtain Scene ID

After creating and saving a Scene on the Kivicube platform, click the “Share” button in the top-right corner, then click “Copy Link.”

The characters that appear after the final slash in the URL are the Scene ID.

For exmaple：https://www.kivicube.com/scenes/n5KxG0svcgNyZof1aWz2kGl6oHNh2JRl, "n5KxG0svcgNyZof1aWz2kGl6oHNh2JRl" will be the scene ID

Hide Scene Logo

hideLogo

Controls whether the Scene logo is shown on the home page.

Default: shown.

(On desktop, the Scene logo does not exist, so this property has no effect.)

Hide Scene Title

hideTitle

Controls whether the Scene title is displayed on the home page.

Default: shown.

Hide Download Progress

hideDownload

Controls whether to display the download progress bar (mobile) or download percentage (desktop).

Default: shown.

Camera Position

cameraPosition

Sets the camera position
- front : front-facing (mirrored)
- back : rear-facing (default)

Hide “Start Experience” Button

hideStart

Whether to forcibly hide the Start button.

If enabled, the Scene will open immediately after assets finish downloading - no user tap required.

Default: not hidden.

This behaves similarly to the “Hide Start Button” option in the Scene Editor, but the plugin will force the behavior regardless of Scene conditions.

WARNING

Note: If the Scene contains auto-play videos or audio, hiding the Start button may prevent autoplay due to browser restrictions.

Hide Loading Indicator

hideLoading

Controls whether to show the loading indicator on AR/3D pages.

Default: shown.

In some cases, loading completes very quickly, so the indicator may barely appear.

For Image Tracking and Cloud Recognition scenes:
The scan UI appears only after scene resources finish loading.
For 3D Interactive scenes:
The 3D content appears immediately once resources are loaded.

Hide Scan UI and Text

hideScan

Controls whether to show the scan UI and instructional text in AR/3D scenes.

Default: shown.

Hide Photo Button

hideTakePhoto

Controls whether to show the built-in photo capture button in AR/3D scenes.

Default: shown.

Hide Scene Background

hideBackground

Controls whether to show or hide the scene background.

Default: shown.

WARNING

Only application to 3D Interactive Scenes

Disable "Open Webpage" Function

disableOpenUrl

Allows you to disable the plugin’s default behavior of opening webpages using location.href = url.

You can listen for the openUrl event, obtain the target URL, and handle the navigation yourself. For example:

open inside your own iframe
open a custom modal
open in a new browser tab
block or filter URLs

Supported Events

Event Order

(image missing)

Page Loaded

load

When it triggers:

Triggered when the Kivicube Web AR plugin script finishes loading and begins opening the Scene, and the plugin has finished downloading the Kivicube page from the server.

After this event, the plugin will start retrieving the Scene data.

Essentially, this event corresponds to the iframe’s native load event.

Best practice

In some network environments, especially under poor network conditions: the plugin script and Kivicube page may take noticeable time to load.

Developers may display a custom loading indicator during this period to improve user experience.

error

error

When it triggers:

This event is triggered whenever an error occurs inside the Kivicube Web AR Plugin.

Error code

Error Phrase	Error Message	Description
Scene Initialization	Failed to retrieve scene information! (200, 404)

Scene Data Retrieved

ready

When it triggers:

This event is fired when the Kivicube Web AR Plugin successfully retrieves the Scene data.
After this event, the plugin will proceed to open the Scene.

Scene Data Structure

sceneInfo

javascript

{
  sceneId: 'sceneid',
  name: 'scenename',
  description: 'scenedescription',
  thumbnailUrl: 'scenethumbnailURL',
  mode: 'scenetype',
  collectionId: 'collectionid',
  collectionName: 'collectionname',
  firstPage: {},
  metadata: {},
  setting: { skipScanMarker: false },
  objects: [{
    id: 'objectid',
    name: 'objectname',
    type: 'objecttype',
  }]
}

Downloading Scene Asset

downloadAssetStart

When it triggers:

This event fires when the Kivicube Web AR Plugin begins downloading the Scene assets.
After this event, asset downloading will proceed immediately.

Notes:

On iOS 15+, AR video and transparent video assets are not downloaded in advance.

They use progressive streaming instead (download while playing).

Asset Download Progress

downloadAssetProgress

Asset Download Completed

downloadAssetEnd

When it triggers:

This event fires when the Kivicube Web AR Plugin finished downloading the Scene assets.

Notes:

On iOS 15+, AR video and transparent video assets are not downloaded in advance.

They use progressive streaming instead (download while playing).

Loading Scene Asset

loadSceneStart

When it triggers:

If “Hide Start Button” is not enabled in the editor, this event triggers after the user taps the “Start Experience” button.
If “Hide Start Button” is enabled, this event triggers immediately after the asset download completes.

Scene Asset Loaded

loadSceneEnd

When it triggers:

Triggered when the Kivicube Web AR Plugin has finished loading all Scene assets.

Scene Started

sceneStart

When it triggers:

Triggered when the Scene content becomes visible and is ready for interaction.

Image Marker Tracked

tracked

When it triggers:

Triggered during the AR experience when the camera successfully detects and tracks an image target.

Note

This event is available only in Image Tracking scenes.

Image Marker Lost

lostTrack

When it triggers

Triggered during the AR experience when the camera loses tracking of the image target.

Note

This event is available only in Image Tracking scenes.

Open Webpage

openUrl

When it triggers:

Triggered when a user interaction in the Scene attempts to open a webpage (e.g., tapping an object that links to a URL).

You may combine this with the disableOpenUrl property to implement custom behaviors, such as:

retrieving the URL only (no navigation)
opening the page inside your own iframe
opening in a modal
opening in a new browser tab

Integrating Kivicube Collection

Automatically Open a Collection

When you add an iframe with the ID kivicubeCollection and specify a collection-id attribute, the imported library will automatically open the corresponding Collection (as shown in the Configuring the iframe Tag section).

Opening a Collection via API

If the iframe does not use the ID kivicubeCollection, or if no collection-id attribute is provided, the developer must manually open the Collection using the API.

javascript

// The global variable `kivicubeIframePlugin` is provided by the imported Kivicube library.
kivicubeIframePlugin.openKivicubeCollection(document.querySelector("iframe"), {
    collectionId: "cqcmzh",
    hideLogo: true,         // Whether to hide the homepage logo. Default: false
    hideTitle: false,       // Whether to hide the homepage title. Default: false
    hideDownload: false,    // Whether to hide the download progress bar. Default: false
    cameraPosition: "back", // Camera direction: front or back. Default: back
    hideStart: false,       // Whether to force-hide the Start button. Default: false
    hideLoading: true,      // Whether to hide the loading indicator. Default: false
    hideScan: false,        // Whether to hide the scan UI and text. Default: false
    hideTakePhoto: false,   // Whether to hide the photo button. Default: false
    disableOpenUrl: false,  // Whether to disable the "open webpage" function. Default: false
});

Closing a Collection

You can close a Collection by directly removing the iframe element (removing it from the DOM and clearing all references), or by changing its src to another URL, or setting it to "about:blank".

Any of these approaches will close the Collection.

However, regardless of which method you choose, you must still call the API to notify the Kivicube library that the Collection has been closed; otherwise, memory leaks may occur.

javascript

const iframe = document.querySelector("iframe");

// Method 1: Clear the iframe content.
// Note: This method does NOT work in iOS WeChat. Use Method 2 instead.
iframe.src = "about:blank";

// Method 2: Load another URL, such as the official empty page:
iframe.src = "https://www.kivicube.com/lib/empty.html";

// Method 3: Remove the iframe from the DOM.
iframe.parentNode.removeChild(iframe);

// IMPORTANT: Regardless of the method used, you MUST call the destroy API.
kivicubeIframePlugin.destroyKivicubeCollection(iframe);

Supported Properties

Collection ID

collectionId

Obtain Collection ID

In the My Collections section of the Kivicube platform, select the Collection you want, open the menu in the bottom-right corner, and copy the Collection ID.

Hide Homepage Logo

hideLogo

Controls whether the Collection’s homepage logo is displayed.

Default: shown.

Hide Homepage Title

hideTitle

Controls whether the Collection’s homepage title is displayed.

Default: shown.

Hide Download Progress

hideDownload

Controls whether the download progress bar is shown (on mobile).

Default: shown.

Camera Position

cameraPosition

Sets the camera position
- front : front-facing (mirrored)
- back : rear-facing (default)

Hide “Start Experience” Button

hideStart

Whether to forcibly hide the Start button.

If enabled, the Collection opens automatically once resources finish downloading—no user action required.

Default: not hidden.

WARNING

If the Collection contains videos or audio that are set to autoplay, enabling this forced-hide option may prevent them from autoplaying.

Hide Loading Indicator

hideLoading

Controls whether to show the loading indicator on AR/3D pages.

Default: shown.

In some cases, loading completes very quickly, so the indicator may barely appear.

For Image Tracking and Cloud Recognition scenes:
The scan UI appears only after scene resources finish loading.
For 3D Interactive scenes:
The 3D content appears immediately once resources are loaded.

Hide Scan UI and Text

hideScan

Controls whether to show the scan UI and instructional text in AR/3D scenes.

Default: shown.

Hide Photo Button

hideTakePhoto

Controls whether to show the built-in photo capture button in AR/3D scenes.

Default: shown.

Disable "Open Webpage" Function

disableOpenUrl

Allows you to disable the plugin’s default behavior of opening webpages using location.href = url.

You can listen for the openUrl event, obtain the target URL, and handle the navigation yourself. For example:

open inside your own iframe
open a custom modal
open in a new browser tab
block or filter URLs

Supported Events

Event Order

(image missing)

Page Loaded

load

When it triggers:

Triggered when the Kivicube Web AR plugin script finishes loading and begins opening the Collection, and the plugin has finished downloading the Kivicube page from the server.

After this event, the plugin will start retrieving the Collection data.

Essentially, this event corresponds to the iframe’s native load event.

Best practice

In some network environments, especially under poor network conditions: the plugin script and Kivicube page may take noticeable time to load.

Developers may display a custom loading indicator during this period to improve user experience.

error

error

When it triggers:

This event is triggered whenever an error occurs inside the Kivicube Web AR Plugin.

Collection Data Retrieved

ready

When it triggers:

This event is fired when the Kivicube Web AR Plugin successfully retrieves the Collection data.
After this event, the plugin will proceed to open the Collection

Collection Data

collectionInfo

javascript

{
  collectionId: 'CollectionID',
  name: 'CollectionName',
  description: 'CollectionDescription',
  thumbnailUrl: 'ThumbnailImageURL',
  functionType: 'CollectionType',
  firstPage: {
    backgroundImageUrl: 'HomepageBackgroundImageURL',
    buttonUrl: 'HomepageButtonImageURL',
    HideLogoAndName: true, // Whether to hide the collection logo and name
  },
  sceneList: ['SceneIDs available within this collection'],
}