kivicube-web-plugin-ar-xr-builder（kivcube 网络插件 ar xr 构建器）

Kivicube Web Plugin AR/XR Builder

Kivicube Web Plugin is an iframe-based integration layer for published scenes and collections used to build AR and XR experiences. The host page owns the iframe, page UI, and event listeners; Kivicube owns the inner experience and exposes a public runtime bridge through iframe-plugin.js. Use this skill from an external integrator's point of view: public script URL, public events, public open props, framework wrappers, and public SceneApi.

Common trigger phrases this skill should match well:

• build a WebAR H5 activity page or AR marketing page
• embed a Kivicube scene in a Vue 3 or React site
• create a branded AR landing page or event page
• build a Web3D product showcase or model viewer
• customize loading, scan, camera, or photo UI for Kivicube
• fix camera permission, autoplay, CORS, or compatibility issues in Kivicube Web

Architecture Model

Host page HTML/CSS/JS
  -> load https://www.kivicube.com/lib/iframe-plugin.js
  -> open a scene or collection into an <iframe>
  -> listen on the iframe for load/ready/progress/tracked/openUrl/error...
  -> for scene pages, read event.detail.api
  -> call async SceneApi methods across the iframe boundary
  -> Kivicube runtime updates objects, media, camera, and rendering

Key split:

• Plain iframe embed: fastest path, no plugin events, no runtime API.
• Plugin + scene: full host events plus SceneApi.
• Plugin + collection: open/close and process events work, but ready.detail.api is not a stable collection runtime API. If you need per-scene runtime hooks inside a collection, read references/patterns.md and references/integration.md for sceneReady.

Common Task Map

Mode Selection

• Use plain iframe embed when the user only needs to show a published scene or collection.
• Use the plugin when the host page needs custom UI, process events, runtime object changes, camera switching, or custom photo flows.
• Prefer scene pages over collection pages when the user needs SceneApi immediately; collection runtime control is narrower and event-driven.
• Prefer manual open when the host uses React, Vue, routing, or explicit mount/unmount logic. Prefer auto-open only for static pages with one obvious iframe.

Key Conventions

• Treat openKivicubeScene() and openKivicubeCollection() as async. This matters most when modifyIframe=false is used in framework wrappers.
• HTML attributes are read once at open time. Changing hide-start, scene-id, or similar attrs later does nothing until the scene or collection is opened again.
• JS props override same-name HTML attrs.
• All SceneApi methods should be awaited.
• Scene objects are opaque handles, not raw three.js objects. Never mutate handle.position or similar fields directly.
• loadSceneEnd is usually the safest point for bulk object queries, runtime additions, and event registration that depend on scene content already existing.
• Always call destroyKivicubeScene() or destroyKivicubeCollection() before reusing the iframe for another scene or collection.
• hideStart is high risk for autoplay and permission flows. Prefer branded host UI that still preserves an explicit user gesture.
• Public Web scene types covered here are image2d-tracking, cloud-ar, and web3d. Do not present face-ar, body-ar, landmark, plane, roam, audio APIs, or custom animation APIs as part of the stable Web plugin surface.

Minimal Path

<script src="https://www.kivicube.com/lib/iframe-plugin.js"></script>
<iframe id="sceneHost" title="Kivicube scene"></iframe>
<script>
  async function main() {
    const iframe = document.getElementById('sceneHost');

    await kivicubeIframePlugin.openKivicubeScene(iframe, {
      sceneId: 'YOUR_32_CHAR_SCENE_ID',
    });

    iframe.addEventListener('ready', async (event) => {
      const api = event.detail.api;
      const obj = await api.getObject('rabbit');
      if (obj) await api.setObjectVisible(obj, true);
    });
  }

  main().catch(console.error);
</script>

Then branch by need:

• Installation, script URL, HTTPS, props, permissions, and deployment: references/integration.md
• Lifecycle, event choreography, host-owned UI, and cleanup: references/patterns.md
• Object lookup, transforms, creation, hierarchy, and destruction: references/scene_objects_reference.md
• Images, panorama, video, GIF, glTF, and animation control: references/media_animation_reference.md
• Rendering, lights, env map, camera, touch forwarding, photo, and cloud-skip: references/rendering_camera_reference.md
• Copyable end-to-end examples, including Vue 3 and React: references/examples.md
• Stable usage guidance and rollout advice: references/best_practices.md
• Symptom-driven debugging: references/troubleshooting.md

API Scope

Treat the public Kivicube Web plugin surface as the source of truth:

• open or destroy a scene or collection through the global plugin object
• listen on the iframe for lifecycle, loading, recognition, URL, and error events
• read event.detail.api on scene pages and call async SceneApi methods
• keep answers limited to the stable Web plugin surface summarized in this skill and its references