--- name: hz-api-upgrade license: Apache-2.0 description: "Upgrades Meta VR apps to newer Horizon OS SDK versions — migration guides, deprecated API replacements, changelog. Use when updating SDK versions or fixing deprecated API warnings. Build paths: all Meta VR app stacks; use hz-quest-verify-first if the build path is unclear." allowed-tools: Bash(metavr:*), Bash(hzdb:*) --- # Horizon API Upgrade Skill For Unity projects using the Meta XR SDK, use the dedicated [`hz-unity-sdk-upgrade`](../hz-unity-sdk-upgrade/SKILL.md) skill. Continue here for Unreal, native Android or Spatial SDK, Web or IWSDK, and general cross-platform upgrade planning. ## When to Use Use this skill when: - Upgrading an existing Meta VR 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 ## General Upgrade Workflow Every SDK upgrade, regardless of platform, follows the same high-level process: ### 1. Identify Current SDK Version 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 ### 2. Check the API Changelog Before upgrading, review what changed between your current version and the target version. See [references/api-changelog.md](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" ``` ### 3. Update SDK Dependencies 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` ### 4. Fix Deprecated API Calls After updating, compile the project and address errors and warnings. See [references/deprecation-guide.md](references/deprecation-guide.md) for common replacements. ```bash # Search project for known deprecated APIs grep -rn "vrapi_" --include="*.c" --include="*.cpp" --include="*.h" src/ grep -rn "OVRManager" --include="*.cs" Assets/ ``` ### 5. Test on Device Deploy and verify functionality on a connected Meta VR device: ```bash metavr app install ./build/output.apk metavr app launch com.yourcompany.yourapp ``` ### 6. Run Performance Check Ensure the upgrade did not introduce performance regressions: ```bash metavr perf capture ``` ## Platform-Specific Upgrade Paths ### 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](references/sdk-migration.md) for the step-by-step Unity upgrade guide. ### 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](references/sdk-migration.md) for the step-by-step Unreal upgrade guide. ### 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](references/sdk-migration.md) for the step-by-step Spatial SDK upgrade guide. ### Web / IWSDK The Immersive Web SDK is distributed as npm packages. Upgrades involve updating package versions in `package.json`. See [references/sdk-migration.md](references/sdk-migration.md) for the step-by-step IWSDK upgrade guide. ## 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. ### Removed APIs 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. ### 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 `` entries for feature declarations ### Manifest Changes Newer SDK versions may require updated `` entries in `AndroidManifest.xml`, such as `com.oculus.supportedDevices` or updated `minSdkVersion` values. ## Android SDK Targeting Requirement New binary uploads for Meta Horizon apps must set `targetSdkVersion` within the supported range. ### 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 ### 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 } } ``` ## Using metavr for Documentation Lookup The `metavr` tool provides documentation search to help during upgrades. Invoke via `metavr ` (published as the npm package `metavr`; if `metavr` is not on PATH, run `npx -y metavr `) — no global install needed. ```bash # 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" ``` ## References - [Deprecation Guide](references/deprecation-guide.md) -- Common deprecated APIs and their replacements - [SDK Migration Guide](references/sdk-migration.md) -- Step-by-step platform-specific migration instructions - [API Changelog](references/api-changelog.md) -- Summary of changes across recent SDK versions