Advanced API

For the full reference and method lists, refer directly to:

• Scene API
• Collection API

The scene advanced API lets the host page directly manipulate scene content inside the iframe.

The collection advanced API lets the host page control the collection-level flow inside the iframe, including opening and closing scenes, but it cannot directly manipulate scene content.

If you want to manipulate scene content inside a collection, wait until a scene is open and then use that scene's advanced API.

You can use it to:

• read or adjust the style and layout of the Start Now Button
• get scene objects and modify position, rotation, visibility, and more
• dynamically create images, models, video, lights, groups, and more
• control video, GIF, and animation playback
• adjust the camera, tone mapping, environment maps, anisotropy, and more
• listen for object-level events such as click, play, pause, and ended
• open or close scenes, start cloud-recognition scanning, stop scanning, and so on

Watermark Note

If you call any advanced API and the current plugin domain is not authorized, a developer watermark will appear.

Get the Advanced API Object

iframe.addEventListener("ready", (event) => {
  const { detail } = event;
  const { api } = detail;
  console.log(api);
});

detail.api is the advanced API object. Scenes and collections use the same access pattern here.

To get the scene advanced API from within a collection:

iframe.addEventListener("sceneReady", (event) => {
  const { detail } = event;
  const { api } = detail;
  console.log(api);
});

Shared Characteristics of the Advanced API

Every API Is Asynchronous

Because communication across the iframe boundary is inherently asynchronous, all API calls, getters, and setters are asynchronous.

So in real development, you should await every API call unless you truly do not care about the result.

const image = await api.getObject("object-name");
await api.setPosition(image, 1, 0, 0);

Retrieved Objects Are Only Handles

You can think of them as pointers. They are object references without local properties or methods, and you cannot control them directly.

const image = await api.getObject("object-name");

image.position.set(1, 0, 0); // ❌ wrong

await api.setPosition(image, 1, 0, 0); // ✅ correct

So you cannot directly mutate image.position.x; you must go through methods such as api.setPosition().

Difference from the Mini Program Plugin

At the moment, detail.api exposes relatively low-level APIs, so the usage is less direct.

Higher-level object-style properties and APIs similar to the Mini Program plugin will be added later.

That is also why the current event.detail gives you detail.api rather than a view object, unlike the Mini Program plugin.

When Creating Content from URLs, CORS Support Is Required

We support building base content in the scene editor and then using advanced APIs to add, remove, or modify content at runtime.

When adding content, the file can be passed in several forms: ArrayBuffer, Blob, File, or URL.

If you pass a URL into the plugin, the hosting server must allow cross-origin access from https://www.kivicube.com.

URL Format

Only absolute URLs are supported: complete URLs that include the protocol, domain, and path, for example: https://your.domain.com/path/to/image.jpg.

Relative URLs are not supported: paths relative to the current page location, for example: /path/to/image.jpg or ../image.jpg.

If you want to use a relative URL, convert it to an absolute URL with new URL('../image.jpg', location.href).href.

For example:

const image = await api.createImage("https://your.domain.com/path/to/image.jpg");
await api.add(image);

In this case, the server at your.domain.com must allow CORS access from the Kivicube domain.

• If you use nginx, you can add configuration like this:

server {
  # Directory that stores asset files
  location /path/to {
    add_header Access-Control-Allow-Origin "https://www.kivicube.com" always;
  }
}

• If you use AWS S3, see https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html

The core requirement is that the response header includes:

Access-Control-Allow-Origin: https://www.kivicube.com

If you pass ArrayBuffer, Blob, or File instead, you can usually ignore CORS configuration because the file is downloaded on your own side first.

const response = await fetch("https://your.domain.com/path/to/image.jpg");
if (response.ok) {
  const imageAb = await response.arrayBuffer();
  const image = await api.createImage(imageAb);
  await api.add(image);
}

Scene API Capability Overview

Start Now Button

Reference: Scene API / Start Now Button

• getStartButtonRect()
• setStartButtonRect(rect)

Object Query and Basic Properties

Reference: Scene API / Object Query and Basic Properties

• getObject(name)
• getAllObjects()
• getObjectName() / setObjectName()
• getObjectVisible() / setObjectVisible()
• getRenderOrder() / setRenderOrder()
• getDisableClick() / setDisableClick()
• getSize()
• lookAt()
• getPosition() / setPosition()
• getRotation() / setRotation()
• getQuaternion() / setQuaternion()
• getScale() / setScale()

Hierarchy and Lifecycle

Reference: Scene API / Object Hierarchy and Lifecycle

• addChild() / removeChild()
• getChildren() / getChildByProperty()
• add()
• remove()
• destroyObject()
• clear()

Dynamic Content Creation

Reference: Scene API / Dynamic Content Creation

• createImage()
• createAnimatedImage()
• createGltfModel()
• createVideo()
• createAlphaVideo()
• createKeyingVideo()
• createPanorama()
• createGroup()
• createAmbientLight()
• createDirectionalLight()
• createEnvMapByHDR()

Media and Animation Control

• Scene API / Animated Images - getAnimatedImagePaused() / playAnimatedImage() / pauseAnimatedImage() / stopAnimatedImage()
• Scene API / Video - getVideoDuration() / getVideoPaused() / getVideoCurrentTime() / setVideoCurrentTime() / getVideoLoop() / setVideoLoop() / playVideo() / pauseVideo() / stopVideo() / playbackVideo()
• Scene API / Audio - getAudioDuration() / getAudioPaused() / getAudioCurrentTime() / setAudioCurrentTime() / getAudioLoop() / setAudioLoop() / playAudio() / pauseAudio() / stopAudio() / playbackAudio()
• Scene API / Animation - playAnimation() / pauseAnimation() / stopAnimation() / playbackAnimation() / getAnimationNames() / isAnimationLoop() / getAnimationIsRunningNames()

Rendering and Lighting

Reference: Scene API / Rendering and Materials, Scene API / Lighting

• setEnableMask() / setDisableMask()
• setGLState()
• setAnisotropy()
• setObjectAlpha()
• getDefaultAmbientLight()
• getDefaultDirectionalLightLeft() / getDefaultDirectionalLightRight()
• getDirectionalLightTarget()
• setLightColor() / setLightIntensity()
• setToneMapping()
• useEnvMapForObj()

Camera and Interaction

Reference: Scene API / Camera and Photo Capture

• getDefaultCamera()
• getCameraFov() / setCameraFov()
• getCameraAspect() / setCameraAspect()
• getCameraNear() / setCameraNear()
• getCameraFar() / setCameraFar()
• updateCameraProjectionMatrix()
• getCameraWorldDirection()
• dispatchTouchEvent(x, y)
• switchCamera(position)
• takePhoto()
• skipCloudar()

Events

Reference: Scene API / Event Listeners

• on(eventName, callback, target?)
• off(eventName, callback, target?)

Collection API Capability Overview

Start Now Button

Reference: Collection API / Start Now Button

• getStartButtonRect()
• setStartButtonRect(rect)

Scene Management

Reference: Collection API / Scene Management

• backToScan()
• openScene(sceneId)
• closeCurrentScene()

Cloud Recognition

Reference: Collection API / Cloud Recognition

• startCloudar(collectionId, sceneIdList)
• stopCloudar()

Camera-Related

Reference: Collection API / Photo Capture

• takePhoto()

Runtime Events

Note: currently supported only by the scene advanced API

The currently available api.on() / api.off() patterns are:

• without target: currently only objectClick, which listens once for clicks on any object
• with target:
  • click - clicked
  • play - audio / video / animation / animated-image playback starts
  • pause - audio / video / animation / animated-image playback pauses
  • ended - audio / video / animation / animated-image playback finishes naturally
  • replay - video / animation / animated-image playback restarts
  • additional object-specific events, described in the "Content and Assets" pages

Example:

const model = await api.getObject('rabbit');

function handleClick(payload) {
  console.log('Object clicked', payload);
}

await api.on('click', handleClick, model);

objectClick

Use this when you need to listen for clicks on any content across the entire scene.

When there are many objects to listen for, or the logic is complex, or you want a single place to handle all clicks, this event acts as event delegation.

Example:

function handleClick(event) {
  // object is a handle, which may be an object or group created in the scene editor,
  // or an object or group created via the Advanced API.
  const { type, name, object } = event;
  // Note: name may be empty, because not every child object has a name.
  // In general, only objects or groups created in the scene editor have names.
  console.log(`Object (${name || 'empty'}) clicked`, type);
}

await api.on('objectClick', handleClick);

Playground - Try the Advanced API Online

Playground

Recommended Reading Path

The following pages explain each capability in more detail:

• Scene API
• Collection API
• 3D Objects
• glTF Models
• Images / Panoramas
• Animated Images
• Video / Alpha Video / Chroma-Key Video
• Lighting
• Environment Maps
• Tone Mapping