Kivicube Docs

English

简体中文

Appearance

Collection API ​

This page describes the advanced runtime API available on collection pages.

How to Get It ​

Get the Collection Advanced API ​

js
iframe.addEventListener('ready', (event) => {
  const api = event.detail.api;
  const collectionInfo = event.detail.collectionInfo;
});

At this point, event.detail.api is a CollectionApi, used to control the overall collection flow.

Get the Current Scene's Advanced API Inside the Collection ​

js
iframe.addEventListener('sceneReady', (event) => {
  const api = event.detail.api;
  const sceneInfo = event.detail.sceneInfo;
});

Here, event.detail.api is a SceneApi, which is the same advanced API you get when opening a scene directly.

Scope ​

This API is currently intended for collection pages.

It is responsible for:

  • reading or adjusting the style and layout of the collection landing page's Start Now Button
  • controlling which scene inside the collection should open
  • closing the current scene
  • starting or stopping recognition in Basic AR/Gyroscope collections
  • returning the collection to scan mode
  • taking photos of the currently opened scene

It is not responsible for directly manipulating objects, models, video, lights, or other scene content.

If you need to control the runtime content of a concrete scene inside the collection, wait for sceneReady and then use the SceneApi it provides.

Shared Conventions ​

Treat Every Method as Asynchronous ​

js
await api.openScene('7A43keFojH0v98xvFP2w52aF8Y67Zbb5');
await api.closeCurrentScene();

Even if some methods only trigger a flow change internally, it is still best to await them consistently.

The api Type Differs Between ready and sceneReady ​

  • ready.detail.api: CollectionApi
  • sceneReady.detail.api: SceneApi

The most common pattern is:

  1. get collection info and CollectionApi in ready
  2. get current scene info and SceneApi in sceneReady
  3. use CollectionApi for scene switching, scan state, and cloud-recognition control in Basic AR/Gyroscope collections
  4. use SceneApi for manipulating objects inside the current scene

Collection API Cannot Manipulate Scene Content Directly ​

Capabilities like the following do not belong to CollectionApi:

  • getting objects, changing position, rotation, or scale
  • adding images, models, or video
  • controlling lights, tone mapping, or environment maps
  • listening for object clicks or video-ended events

Those all belong to SceneApi, which you should obtain from sceneReady.

Full CollectionApi Signature ​

ts
interface CollectionApi {
  getStartButtonRect(): Promise<DOMRect | undefined>;
  setStartButtonRect(rect: Partial<CSSStyleDeclaration>): Promise<void>;

  backToScan(): Promise<void>;
  openScene(sceneId: string): Promise<void>;
  closeCurrentScene(): Promise<void>;

  startCloudar(
    collectionId?: string,
    sceneList?: string[],
  ): Promise<string>;
  stopCloudar(): Promise<void>;

  takePhoto(): Promise<string>;
}

Start Now Button ​

ts
getStartButtonRect(): Promise<DOMRect | undefined>
setStartButtonRect(rect: Partial<CSSStyleDeclaration>): Promise<void>

Used to read or adjust the style and layout of the collection landing page's Start Now Button.

Scene Management ​

ts
backToScan(): Promise<void>
openScene(sceneId: string): Promise<void>
closeCurrentScene(): Promise<void>

openScene(sceneId) ​

Open a concrete scene inside the collection.

js
await api.openScene('7A43keFojH0v98xvFP2w52aF8Y67Zbb5');

Parameters ​

  • sceneId: the scene ID to open. It should usually come from collectionInfo.sceneList.

Notes ​

  • Useful for host-layer interactions such as scene catalogs, next-scene buttons, or jumping to a specific scene.
  • If the current scene is still opening, the call may be rejected. A safer pattern is to wait until after sceneStart before switching away.
  • After opening succeeds, the collection triggers another sequence of sceneReady, download, load, and sceneStart events.

closeCurrentScene() ​

Close the currently opened scene inside the collection.

js
await api.closeCurrentScene();

Notes ​

  • Useful when the host page wants to actively end the current experience, or explicitly clean up before switching scenes.
  • If the close succeeds, the collection triggers a sceneDestroy event.
  • If there is no current scene to close, the call may fail.

backToScan() ​

Return from the current scene back to the scanning state.

js
await api.backToScan();

Notes ​

  • Mainly useful for Basic AR/Gyroscope collections.
  • It closes the current scene first, then re-enters recognition mode.
  • It has no real meaning for non-Basic AR/Gyroscope collections.

Cloud Recognition ​

ts
startCloudar(collectionId?: string, sceneList?: string[]): Promise<string>
stopCloudar(): Promise<void>

startCloudar(collectionId?, sceneList?) ​

Start the cloud-recognition scanning flow.

js
const sceneId = await api.startCloudar(
  collectionInfo.collectionId,
  collectionInfo.sceneList,
);

Parameters ​

  • collectionId: optional. Defaults to the currently opened collection ID.
  • sceneList: optional. Recognition only returns results from the given scene list. Otherwise recognition continues scanning. By default it uses all scenes in the current collection whose type matches the collection type.

Return Value ​

ts
Promise<string>

Returns the recognized scene ID.

Notes ​

  • Only meaningful for Basic AR/Gyroscope collections.
  • If you pass sceneList, recognition results will be limited to those scenes.
  • A common pattern is to filter out the currently opened scene so recognition does not jump back to it immediately.

stopCloudar() ​

Stop the current cloud-recognition scanning flow.

js
await api.stopCloudar();

Notes ​

  • Only meaningful for Basic AR/Gyroscope collections.
  • Useful when the host page wants to take over the pre-recognition flow, show a custom overlay, or temporarily pause recognition.

Photo Capture ​

ts
takePhoto(): Promise<string>

Take a photo of the currently opened scene inside the collection.

js
const photo = await api.takePhoto();
previewImg.src = photo;

Return Value ​

ts
Promise<string>

Returns an image URL in data:image/png;base64,... format.

Notes ​

  • At the moment, a scene must already be open for this to work. Support for taking photos without an open scene may be added later.
  • It is effectively the same as SceneApi.takePhoto(): the result is usually a composite of the currently visible content.

Relationship to Scene API ​

On collection pages, two API types exist at the same time, but their responsibilities differ:

CollectionApi ​

Best for:

  • reading or adjusting the collection landing page's Start Now Button area
  • opening a scene inside the collection
  • closing the current scene
  • returning to scanning
  • starting or stopping cloud recognition
  • taking a photo of the current scene

SceneApi ​

Best for:

  • getting objects and changing position, rotation, or scale
  • dynamically creating images, models, video, lights, and more
  • controlling video, animated images, and animation
  • adjusting the camera, rendering, and materials
  • listening for object-level events

So a typical organization looks like:

js
let collectionApi = null;
let sceneApi = null;

iframe.addEventListener('ready', (event) => {
  collectionApi = event.detail.api;
});

iframe.addEventListener('sceneReady', (event) => {
  sceneApi = event.detail.api;
});