Kivicube文档

简体中文

English

主题

云识别/陀螺仪 ​

云识别合辑对应 cloud-ar 类型。

相比单个云识别场景，云识别合辑的核心特点是：

  • 一个合辑里通常包含多个可被识别后打开的场景
  • 先有合辑级 CollectionApi，再有当前场景级 SceneApi
  • 可以在宿主层主动控制扫描流程，而不只是被动等待识别结果

它和图像 AR 合辑的区别 ​

  • 图像 AR 合辑在“选择要打开哪个场景”这一步，同样默认会使用云识别；区别在于进入具体场景后，还要继续依赖该场景自己的识别图做 tracked / lostTrack
  • 云识别合辑依赖云端图库匹配，通常是“识别到哪张目标，就打开对应场景”

因此云识别合辑比图像 AR 合辑更适合：

  • 目标图不固定、数量较多
  • 需要按业务规则动态限制可识别场景范围
  • 宿主层希望主动开始、停止、恢复扫描

典型流程 ​

云识别合辑常见流程通常是：

  1. 打开合辑
  2. 触发 ready，拿到 collectionInfo 和 CollectionApi
  3. 开始云识别扫描
  4. 识别到目标后，打开对应场景
  5. 触发 sceneReady
  6. 下载素材、加载场景、进入体验
  7. 需要时关闭当前场景并重新回到扫描

因此它比单个场景多了一层“合辑容器 + 场景切换”的概念。

关键事件 ​

宿主层通常至少会关心下面这些事件：

合辑层 ​

  • ready
  • sceneReady
  • sceneDestroy

当前场景层 ​

  • downloadAssetProgress
  • loadSceneEnd
  • sceneStart
  • error
  • incompatibility

当前打开的云识别场景不会再有识别扫描逻辑，相当于合辑中的云识别场景，都默认跳过扫描。

CollectionApi 在云识别合辑中的作用 ​

云识别合辑最值得用到的几组方法是：

js
await api.startCloudar();
await api.stopCloudar();
await api.backToScan();
await api.openScene(sceneId);
await api.closeCurrentScene();

startCloudar() ​

主动开始云识别扫描。

适合：

  • 宿主层有“开始识别”按钮
  • 先展示一层品牌化落地页，再进入扫描
  • 只允许扫描部分场景

stopCloudar() ​

主动停止扫描。

适合：

  • 弹出宿主层说明、遮罩或引导时暂停识别
  • 页面切到非识别状态

backToScan() ​

从当前已打开场景返回到扫描状态。

适合：

  • “继续扫描下一个目标”按钮
  • 多轮识别体验
  • 在合辑里不断切换不同目标内容

常见接入方式 ​

方式一：默认扫描，识别后进入场景 ​

适合快速接入。

宿主层主要监听：

  • ready
  • sceneReady
  • sceneStart
  • error
  • incompatibility

方式二：宿主按钮驱动扫描 ​

例如：

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

  startButton.addEventListener('click', async () => {
    await api.startCloudar();
  });
});

这种方式适合把默认流程与宿主页面品牌化 UI 结合起来。

方式三：从当前场景返回扫描 ​

js
backButton.addEventListener('click', async () => {
  await collectionApi.backToScan();
});

适合“识别一个目标 -> 浏览内容 -> 返回继续识别”的体验。

陀螺仪 ​

云识别场景如果开启陀螺仪，会增加授权和兼容性复杂度。

对云识别合辑来说，这个问题通常更明显，因为：

  • 合辑中可能有多个场景都依赖陀螺仪
  • iOS 和 App 内 WebView 的兼容性风险更高

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

扫描与场景切换的组织方式 ​

一个比较稳妥的宿主层组织方式通常是：

  1. ready 时保存 CollectionApi 和 collectionInfo
  2. sceneReady 时更新当前场景信息和 SceneApi
  3. 切到具体场景后，宿主层显示“返回扫描”“下一目标”等按钮
  4. 用户点击后调用 backToScan() 或 openScene(sceneId)

示例：

js
let collectionApi = null;
let sceneApi = null;

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

iframe.addEventListener('sceneReady', (event) => {
  sceneApi = event.detail.api;
});

适用业务 ​

  • 多目标识别的活动页、寻宝活动、打卡活动
  • 一个入口下组织多个云识别内容
  • 宿主层需要自定义扫描、返回、继续识别流程

接入建议 ​

  1. 优先把“开始扫描”“返回扫描”“停止扫描”这几类操作交给 CollectionApi，不要混用到 SceneApi 上。
  2. 在 sceneReady 之后再获取当前场景的 SceneApi，并在切场景后更新引用。
  3. 如果需要限制当前只识别部分目标，可在 startCloudar(collectionId, sceneList) 中传入子集场景列表。
  4. 对 error 和 incompatibility 做宿主层兜底，尤其是摄像头和兼容性失败。
  5. 如果场景含音视频或复杂交互，真机回归一定要覆盖 iOS 和目标 App 内 WebView。