云识别/陀螺仪

云识别合辑对应 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 在云识别合辑中的作用

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

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

startCloudar()

主动开始云识别扫描。

适合：

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

stopCloudar()

主动停止扫描。

适合：

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

backToScan()

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

适合：

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

常见接入方式

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

适合快速接入。

宿主层主要监听：

• ready
• sceneReady
• sceneStart
• error
• incompatibility

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

例如：

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

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

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

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

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

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

陀螺仪

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

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

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

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

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

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

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

示例：

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。