图像AR

图像 AR 合辑对应 image2d-tracking 类型。

它和单个图像 AR 场景的最大区别在于：

• 合辑先打开的是“合辑容器”，不是某一个具体场景
• 你会先收到 ready，拿到 collectionInfo 和 CollectionApi
• 然后会启用云识别，扫到哪个场景的识别图，则打开哪个场景。
• 当合辑内部真正打开某个场景时，才会收到 sceneReady
• 进入具体场景后，当前场景通过本地识别图进行 tracked / lostTrack
• 当识别图丢失lostTrack时，合辑会再次开启云识别，用来寻找要打开的新场景

体验流程

图像 AR 合辑的典型流程通常是：

1. 打开合辑
2. 触发 ready，拿到合辑信息
3. 合辑默认开启云识别，用来判断应该打开哪个场景
4. 命中某个目标后，打开对应的图像 AR 场景
5. 触发 sceneReady，拿到当前场景信息和对应 SceneApi
6. 下载素材、加载场景
7. 展示当前场景自己的扫描引导
8. 识别到目标图后触发 tracked
9. 丢失目标图时触发 lostTrack。合辑再次开启云识别，用来寻找下一个要打开的新场景

如果你的宿主页面支持“切换到另一个场景”，则后续还会再次触发：

• sceneDestroy
• 下一次 sceneReady

关键事件

图像 AR 合辑最常用的事件通常有两层：

合辑层

• ready
• sceneReady
• sceneDestroy

当前场景层

• downloadAssetProgress
• loadSceneEnd
• sceneStart
• tracked
• lostTrack

可以简单理解为：

• ready 负责“合辑已准备好”
• sceneReady 负责“当前具体场景已准备好”
• tracked / lostTrack 负责“当前图像 AR 场景的识别状态”
• 云识别负责“在合辑层决定下一步该打开哪个场景”

推荐监听方式

let collectionApi = null;
let sceneApi = null;

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

iframe.addEventListener('sceneReady', (event) => {
  sceneApi = event.detail.api;
  console.log('scene ready', event.detail.sceneInfo);
});

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

iframe.addEventListener('lostTrack', () => {
  showScanHint();
});

扫描 UI

图像 AR 合辑里实际上存在两层“扫描”语义：

1. 合辑层的云识别：决定要打开哪个场景
2. 当前图像 AR 场景层的本地识别：决定当前场景是否进入 tracked

因此图像 AR 合辑仍然会在当前场景需要识别时展示默认扫描 UI。

如果你使用：

hideScan: true

则表示你要在宿主层自行承担扫描引导职责。

比较常见的做法是：

1. 在 ready 或 loadSceneEnd 后展示“请扫描目标图”提示
2. 在 tracked 时隐藏提示
3. 在 lostTrack 时重新展示提示
4. 同时意识到 lostTrack 之后，合辑默认还会重新开启云识别，用来寻找下一张可切换到的新场景

如果合辑中的不同场景对应不同识别图，那么宿主层还应根据当前 sceneInfo 更新提示内容，而不是一直复用同一套文案。

和单场景图像 AR 的区别

相比单独打开一个图像 AR 场景，图像 AR 合辑更适合：

• 多张识别图对应多个内容入口
• 在一个入口页下组织多个主题场景
• 宿主层做“场景列表”“下一项”“专题合集”等切换逻辑

同时也要额外注意：

• 不能只监听一次 ready 就认为当前场景信息固定不变
• 宿主层缓存的 SceneApi 应在每次 sceneReady 后更新
• 切换场景时，旧场景对象句柄不应继续复用
• 当前场景内部的 lostTrack 不只是“这个场景暂时没识别到”，它还可能触发合辑重新进入“寻找下一个场景”的流程

自定义交互

图像 AR 合辑常见搭配包括：

• 事件
• 高级API
• Collection API
• 自定义点击
• 拍照和预览

如果你要控制当前具体场景中的模型、图片、视频等内容，应在 sceneReady 中拿到 SceneApi 再操作，而不是直接在 CollectionApi 上调用。

适合什么内容

• 多张海报、卡片、包装分别触发不同场景
• 展览导览、图册导览、门店导览
• 一个活动页里组织多个图像 AR 体验入口

接入建议

1. 先在 ready 中拿到 collectionInfo.sceneList，建立“这个合辑里有哪些场景”的心智模型。
2. 在 sceneReady 中更新当前场景信息和 SceneApi，不要复用上一个场景的对象句柄。
3. 理解图像 AR 合辑默认也会使用云识别：初次打开合辑时会开启，lostTrack 后通常也会再次开启，目的都是为了找到要打开的新场景。
4. 宿主层最好为 tracked / lostTrack 做明确的 UI 反馈，并区分“当前场景识别状态”和“合辑正在寻找下一个场景”。
5. 如果合辑中的场景较多，建议宿主层把“当前是哪个场景”的状态展示出来，避免用户混淆。