# 使用微信小程序模板开发 AR 应用

微信小程序模板使用 XR-FRAME 提供本地跟踪，并调用 01Spatial 获取地图中的绝对相机位姿。所有长期存在的数字内容都应保存在地图坐标中，再整体对齐到当前 trackerSpace。

## 接入前准备

- 小程序已开通相机和 XR 所需能力，并配置合法 HTTPS 请求域名。
- Ready 地图的 Map Key，或 Project Key。
- Portal 个人资料中的 API Key。
- 地图 Origin 与内容坐标已经确认。

## 同步采样

从同一次 `scene.ar.getARRawData()` 结果取得相机数据，并保存与该图片对应的内参、`viewMatrix` 和 camera-to-trackerSpace 变换。不要用普通相机组件、截图或另一个异步视频流替代 XR-FRAME 的同一帧数据。

编码前复制像素、内参和变换。定位响应返回时，先确认当前 XR Session 没有重置，再使用响应中实际命中的 `poses[0].image` 所对应采样帧完成对齐。

## 场景组织

```text
trackerSpace
└── mapRoot              # 应用地图到 trackerSpace 的对齐
    ├── 3D 模型
    ├── 导航路线
    └── 标注
```

不要覆盖 XR-FRAME 相机。可靠定位到达后更新 `mapRoot`，XR-FRAME 继续负责实时相机跟踪。请求格式、置信度处理和坐标公式见[定位 API 与 AR 集成](/tutorials/localization/localization-api)。

## 发布前检查

- 真机上图片、内参和 trackerSpace 变换来自同一 XR 帧。
- 请求域名指向保存地图的同一中国 Portal 环境。
- 网络中断、切到后台和 XR Session 重启后会取消或丢弃过期响应。
- API Key 与 Map/Project Key 不写入公开代码、二维码参数或日志。
- 在计划支持的 Android 和 iOS 微信版本上分别验证。