Back to Details

hz-api-upgrade

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Horizon API Upgrade Skill

Horizon API 升级技能

When to Use

适用场景

Use this skill when:
  • Upgrading an existing Quest application to a newer Horizon OS SDK version
  • Fixing deprecated API warnings or compilation errors after an SDK update
  • Migrating between major API versions (e.g., VrApi to OpenXR)
  • Understanding what changed between SDK releases
  • Planning an upgrade path for a project that has fallen behind on SDK versions
在以下场景中使用本技能：
  • 将现有Quest应用升级至更新的Horizon OS SDK版本时
  • SDK更新后修复废弃API警告或编译错误时
  • 在主要API版本间迁移时（例如从VrApi迁移至OpenXR）
  • 了解SDK版本间的变更内容时
  • 为落后于SDK版本的项目规划升级路径时

General Upgrade Workflow

通用升级流程

Every SDK upgrade, regardless of platform, follows the same high-level process:
无论平台如何，所有SDK升级都遵循相同的高层流程：

1. Identify Current SDK Version

1. 识别当前SDK版本

Determine what version the project currently targets:
  • Unity: Check 
    Packages/manifest.json
    or the Package Manager UI for 
    com.meta.xr.*
    package versions
  • Unreal: Check the Meta XR Plugin version in 
    .uplugin
    files or the Plugins browser
  • Spatial SDK / Android: Check 
    build.gradle
    or 
    build.gradle.kts
    for 
    com.meta.spatial:*
    dependency versions
  • Web / IWSDK: Check 
    package.json
    for 
    @meta-spatial-sdk/*
    or 
    @iwsdk/*
    package versions
确定项目当前目标的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. Check the API Changelog

2. 查看API更新日志

Before upgrading, review what changed between your current version and the target version. See references/api-changelog.md for a summary of recent changes.
Use the device hub to search documentation:
bash
metavr docs search "release notes v72"
metavr docs search "migration guide openxr"
升级前，请查看当前版本与目标版本之间的变更内容。详见references/api-changelog.md获取近期变更摘要。
使用设备中心搜索文档：
bash
metavr docs search "release notes v72"
metavr docs search "migration guide openxr"

3. Update SDK Dependencies

3. 更新SDK依赖

Update the version numbers in your project configuration:
  • Unity: Update via Package Manager or edit 
    manifest.json
    directly
  • Unreal: Download and install the new plugin version
  • Gradle projects: Bump version strings in 
    build.gradle
  • npm projects: Run 
    npm update
    or edit 
    package.json
更新项目配置中的版本号：
  • Unity：通过Package Manager更新或直接编辑
    manifest.json
  • Unreal：下载并安装新版本插件
  • Gradle项目：在
    build.gradle
    中提升版本字符串
  • npm项目：运行
    npm update
    或编辑
    package.json

4. Fix Deprecated API Calls

4. 修复废弃API调用

After updating, compile the project and address errors and warnings. See references/deprecation-guide.md for common replacements.
bash
undefined
更新后，编译项目并处理错误与警告。常见替代方案详见references/deprecation-guide.md。
bash
undefined

Search project for known deprecated APIs

在项目中搜索已知的废弃API

grep -rn "vrapi_" --include=".c" --include=".cpp" --include=".h" src/ grep -rn "OVRManager" --include=".cs" Assets/
undefined
grep -rn "vrapi_" --include=".c" --include=".cpp" --include=".h" src/ grep -rn "OVRManager" --include=".cs" Assets/
undefined

5. Test on Device

5. 设备测试

Deploy and verify functionality on a connected Quest device:
bash
metavr app install ./build/output.apk
metavr app launch com.yourcompany.yourapp
部署并在已连接的Quest设备上验证功能：
bash
metavr app install ./build/output.apk
metavr app launch com.yourcompany.yourapp

6. Run Performance Check

6. 性能检查

Ensure the upgrade did not introduce performance regressions:
bash
metavr perf capture
确保升级未引入性能退化：
bash
metavr perf capture

Platform-Specific Upgrade Paths

平台专属升级路径

Unity: Meta XR SDK

Unity: Meta XR SDK

The Meta XR SDK for Unity is distributed as UPM packages. Upgrades are performed through the Unity Package Manager. Key packages include 
com.meta.xr.sdk.core
, 
com.meta.xr.sdk.interaction
, and 
com.meta.xr.sdk.platform
.
See references/sdk-migration.md for the step-by-step Unity upgrade guide.
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 Engine: Meta XR Plugin

The Meta XR Plugin for Unreal is distributed as an engine plugin. Upgrades involve downloading the new plugin version and regenerating project files.
See references/sdk-migration.md for the step-by-step Unreal upgrade guide.
Unreal版Meta XR Plugin以引擎插件形式分发，升级需下载新版本插件并重新生成项目文件。
Unreal分步升级指南详见references/sdk-migration.md。

Android / Spatial SDK

Android / Spatial SDK

The Meta Spatial SDK is distributed as Gradle dependencies. Upgrades involve bumping version numbers in your Gradle build files.
See references/sdk-migration.md for the step-by-step Spatial SDK upgrade guide.
Meta Spatial SDK以Gradle依赖形式分发，升级需在Gradle构建文件中提升版本号。
Spatial SDK分步升级指南详见references/sdk-migration.md。

Web / IWSDK

Web / IWSDK

The Immersive Web SDK is distributed as npm packages. Upgrades involve updating package versions in 
package.json
.
See references/sdk-migration.md for the step-by-step IWSDK upgrade guide.
Immersive Web SDK以npm包形式分发，升级需更新
package.json
中的包版本。
IWSDK分步升级指南详见references/sdk-migration.md。

Common Upgrade Issues

常见升级问题

Namespace Changes

命名空间变更

Meta has progressively moved from 
Oculus.*
and 
OVR*
namespaces to 
Meta.*
namespaces. After an upgrade, you may see compilation errors due to renamed classes or moved packages.
Meta已逐步从
Oculus.*
和
OVR*
命名空间迁移至
Meta.*
命名空间。升级后，可能会因类重命名或包移动出现编译错误。

Removed APIs

API移除

APIs that were deprecated in previous versions may be fully removed in newer versions. If you skipped intermediate upgrades, you may encounter missing symbols. Always upgrade incrementally.
在旧版本中已废弃的API可能在新版本中被完全移除。如果跳过了中间版本升级，可能会遇到符号缺失问题。请始终逐步升级。

New Required Permissions

新增必填权限

Newer Horizon OS versions may require additional permissions in your 
AndroidManifest.xml
. Common additions include:
  • com.oculus.permission.HAND_TRACKING
    for hand tracking features
  • horizonos.permission.HEADSET_CAMERA
    for passthrough camera access
  • New 
    <meta-data>
    entries for feature declarations
较新版本的Horizon OS可能需要在
AndroidManifest.xml
中添加额外权限，常见新增项包括：
  • 手部追踪功能所需的
    com.oculus.permission.HAND_TRACKING
  • 透视相机访问所需的
    horizonos.permission.HEADSET_CAMERA
  • 用于功能声明的新
    <meta-data>
    条目

Manifest Changes

清单文件变更

Newer SDK versions may require updated 
<meta-data>
entries in 
AndroidManifest.xml
, such as 
com.oculus.supportedDevices
or updated 
minSdkVersion
values.
较新版本的SDK可能需要更新
AndroidManifest.xml
中的
<meta-data>
条目，例如
com.oculus.supportedDevices
或更新
minSdkVersion
值。

Android SDK Targeting Requirement

Android SDK目标版本要求

New binary uploads for Meta Horizon apps must set 
targetSdkVersion
within the supported range.
Meta Horizon应用的新二进制文件上传必须将
targetSdkVersion
设置在支持范围内。

What's required

要求内容

  • Set 
    targetSdkVersion
    to API level 32-34 for immersive apps (or 32-36 for 2D panel apps)
  • minSdkVersion
    can remain at API level 32
  • Applies to all new binary uploads for both new and existing apps
  • Existing published apps continue to work without changes
  • 沉浸式应用需将
    targetSdkVersion
    设置为API级别32-34（2D面板应用为32-36）
  • minSdkVersion
    可保持在API级别32
  • 适用于新应用和现有应用的所有新二进制文件上传
  • 已发布的现有应用无需修改即可继续运行

How to update

更新方式

Unity: Use the Project Setup Tool in the Meta XR SDK -- it can update API versions automatically. Or manually set in Player Settings -> Other Settings -> Target API Level.
Unreal: Use the Project Setup Tool in the Meta XR Plugin. Or set in Project Settings -> Android -> Target SDK Version.
Gradle (Spatial SDK / Native):
groovy
android {
    defaultConfig {
        targetSdkVersion 34  // 32-34 for immersive, 32-36 for 2D panel apps
        minSdkVersion 32
    }
}
Unity：使用Meta XR SDK中的项目设置工具——它可以自动更新API版本。或在Player Settings -> Other Settings -> Target API Level中手动设置。
Unreal：使用Meta XR Plugin中的项目设置工具。或在Project Settings -> Android -> Target SDK Version中设置。
Gradle (Spatial SDK / Native)：
groovy
android {
    defaultConfig {
        targetSdkVersion 34  // 沉浸式应用为32-34，2D面板应用为32-36
        minSdkVersion 32
    }
}

Using metavr for Documentation Lookup

使用metavr查找文档

The 
metavr
tool provides documentation search to help during upgrades. Invoke via 
metavr <args>
(published as the npm package 
metavr
; if 
metavr
is not on PATH, run 
npx -y metavr <args>
) — no global install needed.
bash
undefined
metavr
工具提供文档搜索功能，助力升级工作。通过
metavr <args>
调用（作为npm包
metavr
发布；若
metavr
不在PATH中，可运行
npx -y metavr <args>
）——无需全局安装。
bash
undefined

Search for migration-related documentation

搜索迁移相关文档

metavr docs search "migration guide" metavr docs search "deprecated API" metavr docs search "breaking changes v73"
metavr docs search "migration guide" metavr docs search "deprecated API" metavr docs search "breaking changes v73"

Search for specific API replacements

搜索特定API替代方案

metavr docs search "OVRManager replacement" metavr docs search "vrapi openxr migration"
undefined
metavr docs search "OVRManager replacement" metavr docs search "vrapi openxr migration"
undefined

References

参考资料

  • Deprecation Guide -- Common deprecated APIs and their replacements
  • SDK Migration Guide -- Step-by-step platform-specific migration instructions
  • API Changelog -- Summary of changes across recent SDK versions
  • 废弃API指南——常见废弃API及其替代方案
  • SDK迁移指南——平台专属分步迁移说明
  • API更新日志——近期SDK版本变更摘要