Kivicube Docs

English

简体中文

Appearance

Image AR ​

Image AR collections correspond to the image2d-tracking type.

The biggest difference from a single Image AR scene is:

  • the collection opens a "collection container" first rather than a specific scene
  • you receive ready first, along with collectionInfo and CollectionApi
  • cloud recognition is then used to determine which scene should open
  • only when a real scene inside the collection opens do you receive sceneReady
  • after entering that concrete scene, the scene itself uses its local target image for tracked / lostTrack
  • when tracking is lost on lostTrack, the collection turns cloud recognition back on to find the next scene to open

Experience Flow ​

A typical Image AR collection flow is:

  1. open the collection
  2. trigger ready and receive collection information
  3. the collection starts cloud recognition by default to determine which scene to open
  4. after a target is matched, open the corresponding Image AR scene
  5. trigger sceneReady and receive the current scene info and its SceneApi
  6. download assets and load the scene
  7. show the current scene's own scan guidance
  8. trigger tracked after the target image is recognized
  9. trigger lostTrack when the target image is lost, and the collection starts cloud recognition again to find the next scene to open

If your host page supports switching to another scene, you will later see another round of:

  • sceneDestroy
  • the next sceneReady

Key Events ​

The most commonly used events in an Image AR collection exist on two layers:

Collection Level ​

  • ready
  • sceneReady
  • sceneDestroy

Current Scene Level ​

  • downloadAssetProgress
  • loadSceneEnd
  • sceneStart
  • tracked
  • lostTrack

You can think about them like this:

  • ready means "the collection is ready"
  • sceneReady means "the current concrete scene is ready"
  • tracked / lostTrack describe the recognition state of the current Image AR scene
  • cloud recognition decides which scene should open next at the collection level
js
let collectionApi = null;
let sceneApi = null;

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

iframe.addEventListener('sceneReady', (event) => {
  sceneApi = event.detail.api;
  console.log('scene ready', event.detail.sceneInfo);
});

iframe.addEventListener('tracked', () => {
  hideScanHint();
});

iframe.addEventListener('lostTrack', () => {
  showScanHint();
});

Scan UI ​

An Image AR collection actually contains two layers of "scanning":

  1. collection-level cloud recognition: deciding which scene should open
  2. current scene-level local recognition: deciding whether the current scene enters tracked

So Image AR collections still show the default scan UI when the current scene needs recognition.

If you use:

js
hideScan: true

that means the host layer takes over scan guidance completely.

A common pattern is:

  1. show a "Please scan the target image" hint after ready or loadSceneEnd
  2. hide the hint on tracked
  3. show the hint again on lostTrack
  4. remember that after lostTrack, the collection usually restarts cloud recognition to search for the next scene that can be opened

If different scenes in the collection use different target images, the host layer should update the guidance based on the current sceneInfo instead of reusing the same copy forever.

How It Differs from a Single Image AR Scene ​

Compared with opening a single Image AR scene directly, an Image AR collection is better suited for:

  • multiple target images mapped to multiple content entries
  • organizing multiple themed scenes under one entry point
  • host-layer flows such as "scene list", "next item", or "themed collection"

At the same time, keep these extra considerations in mind:

  • do not assume the current scene info stays fixed just because ready fired once
  • refresh the cached SceneApi every time sceneReady fires
  • do not continue reusing object handles from an old scene after switching
  • lostTrack inside the current scene does not only mean "this scene is temporarily not recognized"; it may also trigger the collection to re-enter the "find the next scene" flow

Custom Interactions ​

Common pairings for Image AR collections include:

If you want to control models, images, videos, and other content inside the current scene, obtain the SceneApi in sceneReady and operate on that instead of calling those methods on CollectionApi.

Suitable Content ​

  • multiple posters, cards, or packages that each trigger a different scene
  • exhibition guides, album guides, and store guides
  • multiple Image AR experience entries organized under a single campaign page

Integration Recommendations ​

  1. Use collectionInfo.sceneList in ready to build a clear mental model of which scenes exist in the collection.
  2. Update the current scene info and SceneApi in sceneReady, and do not reuse object handles from the previous scene.
  3. Understand that Image AR collections also use cloud recognition by default: it starts when the collection first opens, and it usually starts again after lostTrack, both times to find the next scene to open.
  4. The host layer should provide clear UI feedback for tracked / lostTrack, and distinguish between "current scene recognition state" and "the collection is searching for the next scene".
  5. If the collection contains many scenes, it is a good idea to show which scene is currently active so users do not get confused.