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> エントリー

マニフェストの変更

新しいバージョンの 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 バージョンでの変更点の概要