Kivicube Docs

English

简体中文

Appearance

Body AR ​

Body AR corresponds to the body type.

It is mainly used for body tracking and virtual try-on experiences, such as clothing, accessories, body stickers, or 3D content bound to body posture.

Experience Flow ​

A typical flow is:

  1. Open the scene
  2. Download assets
  3. Request camera permission
  4. Load the scene
  5. Start detecting the body
  6. tracked fires once a body is detected
  7. lostTrack fires when the body is lost

Body AR does not rely on a recognition image. The "scanning" here is closer to a "please step back so your whole body is in frame" prompt.

Camera ​

Body AR can use either the front or rear camera depending on your use case:

  • Selfie try-on: use cameraPosition: 'front'
  • Filming others or exhibition interaction: the default rear camera works

Example:

js
await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  cameraPosition: 'front',
});

If the scene configuration allows camera switching, you can also use switchCamera() to switch between front and rear during the experience.

Key Events ​

The most commonly used events in a Body AR scene are:

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

Among them:

  • sceneStart means the scene has started running and the find-person guidance is shown
  • tracked means a body has been detected; the default scan UI hides and photo capture becomes available
  • lostTrack means a body is not being stably detected in the current frame

Scan UI ​

You can hide the default scan UI with the hideScan property, then render your own body-detection prompt on the host layer.

For example:

js
await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  hideScan: true,
});

iframe.addEventListener('sceneStart', () => {
  showBodyGuide('Please step back so your whole body is in frame');
});

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

iframe.addEventListener('lostTrack', () => {
  showBodyGuide('Step back a little and keep your whole body fully in frame');
});

Rather than a generic "scanning", Body AR works better with explicit posture prompts such as "Please keep your shoulders and full body visible" or "Please move to a better-lit spot".

Body Occlusion and Garment Fitting ​

Body AR adds a default body-occlusion / garment-fitting model inside the scene to help align virtual clothing with the full body.

The host page does not need to manage this default model directly. You usually only need to watch:

  • whether the iframe container size is stable
  • whether the camera permission was granted
  • whether the user can keep their whole body in frame as prompted
  • whether the UI is clear across tracked / lostTrack states

Gesture Interaction ​

Body AR supports the rotate and scale gestures configured in the scene.

Currently, gestures mainly act on the body content object, so designing the core experience around dragging objects is not recommended. Preferred interaction patterns are:

  • the user moves their body or adjusts distance to align
  • the host layer provides buttons to switch style, color, size, etc.
  • the user saves the result via photo capture or screen recording

Suitable Use Cases ​

  • Virtual try-on, top/shirt fitting
  • Apparel, accessories, or IP characters aligned to the body
  • Exhibition large screens or mobile selfie experiences
  • Outfit marketing campaigns that need photo sharing

Integration Tips ​

  1. For selfie try-on, set cameraPosition: 'front' first; otherwise the user may need someone else to film them.
  2. Guide users to keep their whole body in frame. Tracking becomes less stable when the shoulders or chest area is occluded.
  3. Body AR is sensitive to distance, lighting, and background complexity. Validate on real mobile devices.
  4. If you hide the default scan UI, the host layer must maintain clear find-person prompts across sceneStart / tracked / lostTrack.
  5. Before photo capture or screen recording, confirm tracked has fired at least once, to avoid saving a frame where fitting is incomplete.