Kivicube Docs

English

简体中文

Appearance

Face AR ​

Face AR corresponds to the face type.

It is mainly used to bind 3D content to the user's face, such as glasses, headwear, masks, makeup, face stickers, and so on.

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 face
  6. tracked fires once a face is detected
  7. lostTrack fires when the face is lost

Unlike Image AR, Face AR does not need a recognition image. The "scanning" here is closer to a "please put your face in frame" prompt.

Camera ​

Face AR uses the front camera by default.

If the scene configuration allows camera switching, switchCamera() can still switch to the rear camera; however, the rear camera is usually only suitable when someone else is filming, and is not recommended as the default entry point.

Key Events ​

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

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

Among them:

  • sceneStart means the scene has started running and the find-face guidance is shown
  • tracked means a face has been detected; the default scan UI hides and photo capture becomes available
  • lostTrack means a face 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 find-face prompt on the host layer.

For example:

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

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

iframe.addEventListener('lostTrack', () => {
  showFaceGuide('Please move your face into frame');
});

Custom prompts work better when they are specific, such as "Please face the screen" or "Move to a brighter spot if it is too dark" — these are easier for users to understand than a plain "scanning".

Gesture Interaction ​

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

Currently, gestures mainly act on the face content object and do not include a default face-occlusion model. Dragging and tapping are not the primary interaction for Face AR, so it is better to design interactions around:

  • the user moving their head to change the viewpoint
  • the user switching style, color, or effect via buttons
  • the user sharing via photo capture or screen recording

Suitable Use Cases ​

  • Virtual try-on for glasses, hats, and headwear
  • Selfie effects such as masks, makeup, and stickers
  • Face effects on brand campaign pages
  • Interactive marketing scenarios that need photo sharing

Integration Tips ​

  1. Validate on real mobile devices first. The face-camera experience on desktop browsers differs significantly from phones.
  2. Use the front camera by default; do not make the rear camera the main path for Face AR.
  3. If you hide the default scan UI, the host layer must maintain clear find-face prompts across sceneStart / tracked / lostTrack.
  4. Face AR is sensitive to lighting, distance, and occlusion. Provide simple posture and lighting guidance on the page.
  5. Before photo capture or screen recording, confirm tracked has fired at least once, to avoid the user saving a frame where content is not correctly fitted.