Kivicube文档

简体中文

English

主题

面部AR ​

面部 AR 对应 face 类型。

它主要用于把 3D 内容绑定到用户面部，例如眼镜、头饰、面具、妆容、脸部贴纸等。

体验流程 ​

典型流程如下：

  1. 打开场景
  2. 下载素材
  3. 请求摄像头权限
  4. 加载场景
  5. 开始检测人脸
  6. 检测到人脸后触发 tracked
  7. 丢失人脸时触发 lostTrack

和图像 AR 不同，面部 AR 不需要识别图。这里的“扫描”更接近“请把脸放入画面”的引导。

摄像头 ​

面部 AR 默认使用前置摄像头。

如果场景配置允许切换摄像头，switchCamera() 仍然可以切换到后置摄像头；但后置摄像头通常只适合他人协助拍摄，不建议作为默认入口。

关键事件 ​

面部 AR 场景最常用的几个事件是：

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

其中：

  • sceneStart 表示场景已经开始运行，此时会展示找脸引导
  • tracked 表示检测到人脸，默认扫描 UI 会隐藏，拍照能力可用
  • lostTrack 表示当前画面中暂时未稳定检测到人脸

扫描 UI ​

你可以通过属性 hideScan 隐藏默认扫描 UI，然后在宿主层自己渲染找脸提示。

例如：

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

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

iframe.addEventListener('lostTrack', () => {
  showFaceGuide('请将面部移入画面');
});

自定义提示建议更具体一些，例如“请正对屏幕”“光线太暗时请移动到明亮处”，比单纯的“扫描中”更容易被用户理解。

手势交互 ​

面部 AR 支持场景配置中的旋转、缩放手势。

当前手势主要作用在面部内容对象上，不包含默认面部遮挡模型；拖拽和点击不是面部 AR 的主要交互方式，建议优先把交互设计成：

  • 用户移动头部改变视角
  • 用户通过按钮切换款式、颜色或效果
  • 用户通过拍照/录屏完成分享

推荐搭配 ​

适用业务 ​

  • 虚拟试戴眼镜、帽子、头饰
  • 面具、妆容、贴纸等自拍玩法
  • 品牌活动页中的人脸特效
  • 需要拍照分享的互动营销场景

接入建议 ​

  1. 优先在移动端真实设备上验证，桌面浏览器的人脸摄像头体验和手机差异较大。
  2. 默认使用前置摄像头，不要把后置摄像头作为面部 AR 的主路径。
  3. 如果隐藏默认扫描 UI，宿主层要在 sceneStart / tracked / lostTrack 之间维护清晰的找脸提示。
  4. 面部 AR 对光线、距离和遮挡比较敏感，建议在页面上给出简单的姿态和光线引导。
  5. 拍照或录屏前，最好确认已经触发过 tracked，避免用户保存到没有正确贴合的画面。