Quick Start

Note

This page only covers the Web plugin. If you want to learn how to use the Mini Program plugin, open the Mini Program plugin guide instead.

Embed Directly with a Regular Webpage iframe

If you only need to display a scene and do not need events or advanced APIs, a regular iframe is enough.

<iframe
  src="https://www.kivicube.com/scenes/lU0kh9MnQBxa15Op5tcl3SJV53FWcSk6"
  allow="xr-spatial-tracking;camera;microphone;autoplay;fullscreen;gyroscope;accelerometer"
  frameborder="0"
  width="100%"
  height="100%"
></iframe>

Important

The host page that contains the iframe must run on https, or on http://localhost with any port.

Otherwise the page inside the iframe will not be able to obtain camera permission correctly. In practice this usually means AR cannot start, or the page shows a compatibility warning such as "Only iOS 11 and above is supported".

We do not recommend testing directly on a phone with a LAN address such as 192.168.x.x, 10.x.x.x, or 172.16-31.x.x, unless that address is already configured with accessible HTTPS. A safer approach is to deploy to an HTTPS-enabled environment before testing.

Replace src with your own scene or collection URL. In the Kivicube platform, you can copy the corresponding address from "Development & Integration".

Collections are embedded in exactly the same way as scenes. Just replace the URL with /collections/<collectionId>.

Embed as a Plugin

Use the official iframe plugin if you need to:

• hide the default landing page elements
• customize host-layer buttons and status messages
• listen for events such as download, load, recognition, and navigation
• add images, models, videos, and other content at runtime
• read objects and modify parameters such as position, rotation, lighting, and camera settings

Capability	Regular iframe	Plugin mode
Custom UI	Not supported	Supported
Event callbacks	Not supported	Supported
Add / remove / update AR content	Not supported	Supported
Custom photo capture	Not supported	Supported
More 3D rendering control	Not supported	Supported

1. Load the Plugin Script

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

2. Prepare the iframe Element

<style type="text/css">
  iframe#kivicubeScene,
  iframe#kivicubeCollection {
    /* Set the size as needed */
    width: 100vw;
    height: calc(100vw * (4 / 3));
    /* Remove the default browser border */
    border: none;
  }
</style>

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

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

If the iframe has the id kivicubeScene or kivicubeCollection, and it already exists when DOMContentLoaded fires, the plugin will automatically read scene-id or collection-id and open it.

Notes

iframe on iOS Does Not Support the Gyroscope

On iOS host pages, access to gyroscope authorization is blocked. To improve compatibility, we recommend disabling gyroscope-dependent behavior for all content embedded with an iframe whenever possible.

The gyroscope is involved in the following two scene types:

1. "Basic AR/Gyroscope" scenes. Turn off the "Gyroscope" option in Advanced Settings.

2. "Image AR" scenes. Turn off the "Gyroscope" option in Advanced Settings.

For collections, make sure the related scenes inside the collection also have this option disabled.

Supported Scene Types

The iframe plugin currently focuses on:

• image2d-tracking - Image AR
• cloud-ar - Basic AR/Gyroscope
• web3d - 3D

Other types do not yet expose equivalent advanced iframe APIs on the Web, but support is planned soon. See the later Scene Types section for details.

Supported Collection Types

The iframe plugin currently focuses on:

• image2d-tracking - Image AR
• cloud-ar - Basic AR/Gyroscope

Other types do not yet expose equivalent advanced iframe APIs on the Web. See the later Collection Types section for details.

Plan Support

All registered users can embed their own scenes and collections in an iframe on their website.

Support still varies by plan:

Free and Starter plan users will see a watermark on scenes and collections.

Pro and Enterprise plan users will see scenes and collections without a watermark.

If you use plugin mode and also use properties or advanced API features, the regular watermark switches to a developer watermark instead.

The developer watermark can only be removed through domain authorization. See the next page, Remove the Watermark, for details.