Image AR

Image AR corresponds to the image2d-tracking type.

Experience Flow

A typical flow looks like this:

1. open the scene
2. download assets
3. load the scene
4. show scanning guidance
5. trigger tracked after the camera recognizes the target image
6. trigger lostTrack when the target image is lost

Key Events

The most commonly used events in Image AR scenes are:

• ready
• downloadAssetProgress
• loadSceneEnd
• sceneStart
• tracked
• lostTrack

Scan UI

You can hide the default scanning UI with the hideScan property and render your own guidance on the host layer.

If the scene is configured with a custom scan image, scan copy, or an entry for downloading the target image, the default Kivicube UI handles that automatically. If you fully customize the host UI, you need to provide those guides and implementations yourself.

Gyroscope Mode

Image AR scenes also support gyroscope-related behavior:

• if the scene enables the gyroscope, the experience can continue with gyroscope logic after tracking is lost
• on iOS, that also introduces motion and orientation permission handling

So for iframe integrations, it is still recommended to disable the gyroscope first whenever possible.

Custom Interactions

Image AR scenes are commonly paired with:

• Custom Touch
• Photo Capture and Preview
• Images / Panoramas
• glTF Models

Suitable Content

• recognizing posters, packaging, albums, or cards
• showing 3D models, video, animated images, and other content after recognition
• brand marketing and exhibition guidance

Integration Recommendations

1. Make the target image as clear as possible and rich in feature points.
2. The host page should ideally provide a clear "Please scan the target image" hint.
3. Adding visual feedback for tracked and lostTrack makes the experience much more stable for users.