Kivicube文档

简体中文

English

主题

云识别/陀螺仪 ​

云识别场景对应 cloud-ar 类型。

它和图像 AR 的区别 ​

  • 图像 AR 依赖本地识别图，3D场景内容都出现在识别图上
  • 云识别依赖云端百万级图库识别能力，3D场景内容直接出现在屏幕上(可启用陀螺仪)。

因此在体验上，云识别可跳过扫描，或强制需要扫描皆可。但图像AR必须扫描才能体验。

典型流程 ​

  1. 打开场景
  2. 下载素材
  3. 加载场景
  4. 等待云识别扫描到
  5. 然后进入体验

如果场景配置了跳过云识别扫描，流程会更短。

跳过云识别 ​

当前高级 API 明确提供了：

js
await api.skipCloudar();

这个方法会：

  1. 停止云识别扫描
  2. 立即进入后续流程

也就是说，它本质上是“跳过等待扫描，直接进入体验”。

适合什么场景 ​

  • 你已经在宿主页面里做过自己的识别前置流程
  • 你希望用户可以点击“跳过扫描，直接预览”，或者在一定时间后自动跳过。
  • 你需要在某些运营链路里快速进入内容
  • 场景编辑器中必须配置为需要识别，但要符合某些动态条件时才跳过云识别。

使用示例 ​

js
iframe.addEventListener('ready', (event) => {
  const { api } = event.detail;

  skipButton.addEventListener('click', async () => {
    await api.skipCloudar();
  });
});

注意 ​

  • 这个方法只对云识别场景有效。
  • 如果当前场景本来就配置了跳过扫描，调用它不会带来额外效果。
  • 建议把“跳过扫描”作为显式用户动作，而不是默认自动执行，否则会削弱云识别内容原本的体验设计。

陀螺仪 ​

云识别场景如果开启陀螺仪，加载完成后会进一步接入陀螺仪控制逻辑。

这会带来两个现实问题：

  • 授权链路更复杂
  • iOS 与 App 内 WebView 的兼容性风险更高

因此对 Web iframe 接入而言，建议优先关闭陀螺仪。

宿主层推荐监听 ​

  • ready
  • downloadAssetProgress
  • loadSceneEnd
  • sceneStart
  • error
  • incompatibility

适用业务 ​

  • 需要基于云端图像库匹配的场景，支持百万级图库识别
  • 不方便提前让用户拿到明确识别图的活动，比如寻宝
  • 希望在识别成功后再进入内容展示