AR XR Builder

Use when building, embedding, customizing, or troubleshooting AR/XR experiences with the Kivicube Web Plugin, including WebAR/Web3D H5 pages, landing pages,...

Security Scan

The skill is an instruction-only guide for integrating the public Kivicube Web Plugin and its requirements and instructions are consistent with that purpose.

Purpose & Capability

The name and description claim iframe-based integration with the Kivicube Web Plugin; all files and the SKILL.md focus on loading the public script (https://www.kivicube.com/lib/iframe-plugin.js), embedding scenes/collections, and using the documented SceneApi. There are no unrelated environment variables, binaries, or installs requested.

Instruction Scope

Runtime instructions and code samples are narrowly scoped to host-page tasks (loading the public script, opening scenes/collections, listening to iframe events, using SceneApi, CORS guidance, and cleanup). The instructions do not ask the agent to read local files, environment secrets, or contact endpoints outside the documented Kivicube domain. They do advise host-side fetch-and-pass ArrayBuffer for CORS/auth scenarios, which is expected for asset handling.

Install Mechanism

There is no install spec and no code files to write or execute. This is instruction-only documentation, so nothing is downloaded or installed by the skill itself.

Credentials

The skill requests no environment variables, credentials, or config paths. All examples rely on the public Kivicube script and public scene/collection IDs, which match the stated purpose.

Persistence & Privilege

The skill is not marked always:true and uses the platform defaults for invocation. There is no installation step that modifies other skills or system-wide settings.

Assessment

This skill is a documentation/manual-integration pack for the public Kivicube Web Plugin and appears internally consistent. Before using it, confirm you trust https://www.kivicube.com because the examples require loading their remote script and iframe content. No credentials are requested, but be mindful of CORS and asset hosting: if your assets require auth or you don't want to expose them via public URLs, follow the guidance to fetch them in the host and pass ArrayBuffer. Also test on real mobile devices and avoid removing the user gesture (hideStart) unless you understand the autoplay and permission impacts.

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

Task	Public entry point
Plain embed with no customization	direct iframe embed with a published scene or collection URL
Open a scene manually	openKivicubeScene()
Open a collection manually	openKivicubeCollection()
Auto-open before DOMContentLoaded	iframe id + scene-id or collection-id
Keep framework components in control of DOM attrs	openKivicubeScene(..., false) / openKivicubeCollection(..., false)
Start from Vue 3 or React	references/examples.md framework examples
React to loading or scan progress	iframe events: downloadAssetProgress, loadSceneStart, tracked, lostTrack
Get the runtime API	iframe ready event, then event.detail.api
Find or move an object	getObject(), setPosition(), setRotation(), setScale()
Add runtime content	createImage(), createGltfModel(), createVideo(), then add()
Clean up runtime objects	remove(), destroyObject(), destroyKivicubeScene()
Switch camera or take a photo	switchCamera(), takePhoto()
Forward host clicks into the scene	dispatchTouchEvent()
Skip cloud recognition	skipCloudar()
Diagnose permissions, autoplay, or CORS failures	references/troubleshooting.md

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