hz-api-upgrade

Horizon API 升级技能

对于使用 Meta XR SDK 的 Unity 项目，请使用专用的 hz-unity-sdk-upgrade 技能。对于 Unreal、原生 Android 或 Spatial SDK、Web 或 IWSDK，以及通用跨平台升级规划，请继续阅读本文。

适用场景

在以下情况下使用此技能：

• 将现有 Meta VR 应用升级到较新的 Horizon OS SDK 版本
• 修复 SDK 更新后出现的已弃用 API 警告或编译错误
• 在主要 API 版本之间迁移（例如，从 VrApi 迁移到 OpenXR）
• 了解 SDK 版本之间的变更
• 为 SDK 版本落后的项目规划升级路径

通用升级工作流

无论使用哪种平台，每次 SDK 升级都遵循相同的高级流程：

1. 确定当前 SDK 版本

确定项目当前面向的版本：

• Unity：检查 Packages/manifest.json，或在 Package Manager UI 中查看 com.meta.xr.* 包版本
• Unreal：检查 .uplugin 文件或 Plugins 浏览器中的 Meta XR Plugin 版本
• Spatial SDK / Android：检查 build.gradle 或 build.gradle.kts 中的 com.meta.spatial:* 依赖版本
• Web / IWSDK：检查 package.json 中的 @meta-spatial-sdk/* 或 @iwsdk/* 包版本

2. 查看 API 更新日志

升级前，请查看当前版本与目标版本之间的变更。近期变更摘要请参阅 references/api-changelog.md。

使用设备中心搜索文档：

metavr docs search "release notes v72"
metavr docs search "migration guide openxr"

3. 更新 SDK 依赖项

更新项目配置中的版本号：

• Unity：通过 Package Manager 更新，或直接编辑 manifest.json
• Unreal：下载并安装新版本的插件
• Gradle 项目：更新 build.gradle 中的版本字符串
• npm 项目：运行 npm update，或编辑 package.json

4. 修复已弃用的 API 调用

更新后，编译项目并处理错误和警告。常见替换方式请参阅 references/deprecation-guide.md。

# Search project for known deprecated APIs
grep -rn "vrapi_" --include="*.c" --include="*.cpp" --include="*.h" src/
grep -rn "OVRManager" --include="*.cs" Assets/

5. 在设备上测试

在已连接的 Meta VR 设备上部署并验证功能：

metavr app install ./build/output.apk
metavr app launch com.yourcompany.yourapp

6. 运行性能检查

确保升级未导致性能退化：

metavr perf capture

平台专属升级路径

Unity：Meta XR SDK

Unity 版 Meta XR SDK 以 UPM 包的形式分发。通过 Unity Package Manager 执行升级。主要包包括 com.meta.xr.sdk.core、com.meta.xr.sdk.interaction 和 com.meta.xr.sdk.platform。

Unity 升级步骤指南请参阅 references/sdk-migration.md。

Unreal Engine：Meta XR Plugin

Unreal 版 Meta XR Plugin 以引擎插件的形式分发。升级需要下载新版本的插件并重新生成项目文件。

Unreal 升级步骤指南请参阅 references/sdk-migration.md。

Android / Spatial SDK

Meta Spatial SDK 以 Gradle 依赖项的形式分发。升级需要更新 Gradle 构建文件中的版本号。

Spatial SDK 升级步骤指南请参阅 references/sdk-migration.md。

Web / IWSDK

Immersive Web SDK 以 npm 包的形式分发。升级需要更新 package.json 中的包版本。

IWSDK 升级步骤指南请参阅 references/sdk-migration.md。

常见升级问题

命名空间变更

Meta 已逐步将 Oculus.* 和 OVR* 命名空间迁移到 Meta.* 命名空间。升级后，你可能会因类重命名或包迁移而遇到编译错误。

已移除的 API

先前版本中已弃用的 API 可能会在较新版本中被彻底移除。如果跳过了中间版本的升级，可能会遇到符号缺失的问题。请始终逐步升级。

新增必需权限

较新版本的 Horizon OS 可能要求在 AndroidManifest.xml 中添加其他权限。常见的新增项包括：

• 用于手部追踪功能的 com.oculus.permission.HAND_TRACKING
• 用于访问透视摄像头的 horizonos.permission.HEADSET_CAMERA
• 用于声明功能的新 <meta-data> 条目

Manifest 变更

较新版本的 SDK 可能要求更新 AndroidManifest.xml 中的 <meta-data> 条目，例如 com.oculus.supportedDevices，或更新 minSdkVersion 值。

Android SDK 目标版本要求

Meta Horizon 应用的新二进制文件上传必须将 targetSdkVersion 设为支持范围内的值。

要求

• 沉浸式应用的 targetSdkVersion 设为 API 级别 32-34（2D 面板应用为 32-36）
• minSdkVersion 可保持为 API 级别 32
• 适用于所有新二进制文件上传，包括新应用和现有应用
• 已发布的现有应用无需变更即可继续运行

如何更新

Unity： 使用 Meta XR SDK 中的 Project Setup Tool，即可自动更新 API 版本。也可以在 Player Settings -> Other Settings -> Target API Level 中手动设置。

Unreal： 使用 Meta XR Plugin 中的 Project Setup Tool。也可以在 Project Settings -> Android -> Target SDK Version 中设置。

Gradle（Spatial SDK / Native）：

android {
    defaultConfig {
        targetSdkVersion 34  // 32-34 for immersive, 32-36 for 2D panel apps
        minSdkVersion 32
    }
}

使用 metavr 查找文档

metavr 工具提供文档搜索功能，可在升级过程中提供帮助。通过 metavr <args> 调用（以 npm 包 metavr 的形式发布；如果 metavr 不在 PATH 中，请运行 npx -y metavr <args>）——无需全局安装。

# Search for migration-related documentation
metavr docs search "migration guide"
metavr docs search "deprecated API"
metavr docs search "breaking changes v73"

# Search for specific API replacements
metavr docs search "OVRManager replacement"
metavr docs search "vrapi openxr migration"

参考资料

• 弃用指南 -- 常见的已弃用 API 及其替代项
• SDK 迁移指南 -- 分步的平台专属迁移说明
• API 变更日志 -- 近期 SDK 版本变更摘要