# 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).

Contact Us

*** ## 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 {% hint style="warning" %} Pages that embed the plugin using an iframe (your custom H5 page) must run over HTTPS, or be accessed via . 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. {% endhint %} ### Importing Kivicube Library Code ```html ``` ### Configuring iframe Tag ```html ``` *** ## 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：, "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. {% hint style="warning" %} Note: If the Scene contains auto-play videos or audio, hiding the Start button may prevent autoplay due to browser restrictions. {% endhint %} #### 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.* {% hint style="warning" %} Only application to 3D Interactive Scenes {% endhint %} #### 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](https://cloud.kivicube.com/collections), 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.* {% hint style="warning" %} If the Collection contains videos or audio that are set to autoplay, enabling this forced-hide option may prevent them from autoplaying. {% endhint %} #### 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'], } ``` *** #### Scene Ready (Within Collection) > sceneReady This event works the same way as the Scene event *** #### Downloading Scene Asset > downloadAssetStart This event works the same way as the Scene event *** #### Asset Download Progress > downloadAssetProgress This event works the same way as the Scene event *** #### Asset Download Completed > downloadAssetEnd This event works the same way as the Scene event *** #### Loading Scene Asset > loadSceneStart This event works the same way as the Scene event *** #### Scene Asset Loaded > loadSceneEnd This event works the same way as the Scene event *** #### Scene Started > sceneStart This event works the same way as the Scene event *** #### Image Marker Tracked > tracked This event works the same way as the Scene event *** #### Image Marker Lost > lostTrack This event works the same way as the Scene event *** #### Open Webpage > openUrl This event works the same way as the Scene event *** #### Scene Deleted (within Collection) > sceneDestroy The event parameters include the ID of the Scene being closed. **When it triggers** * When the user taps the Back button to return to the scan screen. *(Only triggered when the Collection is of the Cloud Recognition type.)* * When another Scene of the same type within the same Collection is scanned. In this case, the current Scene will close first, and then the new Scene will open. *** ## Demo code * **Demo Experience**： * To view the demo code, copy the URL below into your browser’s address bar:view-source: ### More Demos ## Code Template: