hz-android-2d-porting

Horizon OS への Android 2D アプリの移植

使用する場面

次のような場合に、このスキルを使用します。

• 既存の Android 2D アプリを Meta VR ヘッドセットで動作するように移植する
• モバイル Android アプリを Horizon OS のパネルに対応させる
• Meta VR デバイス上の 2D アプリで、入力、レイアウト、互換性の問題をトラブルシューティングする
• Horizon Store への Android アプリの申請準備をする
• 既存の Android アプリが Horizon OS と互換性があるか評価する

概要

Horizon OS は Android（AOSP）を基盤としており、3D 空間に配置されるフローティング 2D ウィンドウであるパネル内で、標準的な Android アプリケーションを実行できます。適切に構築された Android アプリの多くは、最小限の変更で Meta VR デバイス上でも動作しますが、いくつかの点に注意が必要です。

1. 入力：タッチスクリーンはありません。ユーザーはコントローラーポインター（レイキャスティング）、ハンドトラッキング、または接続した周辺機器を使用して操作します。
2. レイアウト：アプリは固定ディスプレイで全画面表示されるのではなく、サイズ変更可能なパネルで実行されます。
3. 互換性：Google Play Services がなくても、または利用できないハードウェアがなくても、依存関係と権限が正常に動作する必要があります。
4. デザインとパフォーマンス：アプリはモバイルハードウェア上で Horizon Store の要件を満たす必要があります。

移植の目的は、既存の機能を維持しつつ、アプリを Meta VR のエクスペリエンスに自然に溶け込ませることです。

移植ワークフロー

ステップ 1：初期テスト

通常の Android ワークフローで既存のアプリをビルドしてインストールします。Android Studio、Gradle、adb は、接続した Meta VR デバイスで使用できます。

./gradlew installDebug
adb shell am start -n com.example.yourapp/.MainActivity

ここでは生の adb よりも metavr app install <apk> と metavr app launch <package> を優先し、初回起動中は metavr adb logcat --follow でログをストリーミングしてください。すぐに発生するクラッシュ、黒い画面、入力の問題、レイアウトの崩れがないか確認します。

ステップ 2：互換性の監査

UI を変更する前に、アプリが Google Play Services、サポート対象外のハードウェア、または禁止されている権限に依存していないか確認します。サポートされない機能はオプションにするか、Horizon OS の代替機能に置き換えてください。互換性要件を参照してください。

ステップ 3：入力の適応

移植で最もよくある問題は入力です。タッチイベントはコントローラーポインターから変換されますが、次の点に注意してください。

• ホバー状態が表示されます（ユーザーはクリックする前にポインターを合わせます）
• スクロールにはスワイプ操作ではなくサムスティックを使用します
• マルチタッチ操作（ピンチしてズーム）はそのままでは反映されません
• タップ対象はポインターの精度に合わせて十分な大きさが必要です（最小 48dp）

詳しいガイダンスについては、入力適応リファレンスを参照してください。

ステップ 4：レイアウトの調整

パネルはサイズ変更が可能で、さまざまなアスペクト比にできます。アプリは次の項目に対応する必要があります。

• 幅と高さの動的な変更
• 横向きと縦向き
• 異なる実効 DPI 値

レスポンシブな Android レイアウトとウィンドウサイズのブレークポイントを使用してください。パネルレイアウトリファレンスを参照してください。

ステップ 5：Gradle とマニフェストの更新

Horizon OS を対象とするよう、ビルド設定を更新します。

// build.gradle.kts
android {
    defaultConfig {
        minSdk = 29       // Android 10 minimum
        targetSdk = 34    // API 34 or higher required for all new 2D panel apps
    }
}

デバイスのターゲティングに必要なマニフェストエントリーを追加してください。Gradle セットアップリファレンスを参照してください。

ステップ 6：入力テスト

サポートされているすべての入力方法でテストします。

• コントローラー：ポインティングとクリック、サムスティックでのスクロール、トリガーでのタップ
• ハンドトラッキング：ピンチで選択、手でのスクロール
• キーボード／マウス：Bluetooth 周辺機器、テキストフィールド用のシステムキーボード

デスクトップでの反復作業には Meta Spatial Simulator を使用し、その後、Meta Horizon OS Android Studio プラグインまたは通常の ADB ツールで実機検証します。入力テストを行うたびに metavr adb logcat --follow を実行しておいてください。画面上ではクラッシュとして見えない入力エラーを検出できます。

ステップ 7：ストアへの申請

Horizon Store に申請する前に、次の項目を確認してください。

• すべての互換性要件を満たしていることを確認する
• Quest 3、Quest 3S、Quest 2（対象とする場合）に加え、Meta VR Glasses でもテストする
• パススルー環境とイマーシブホーム環境の両方でアプリが動作することを確認する
• Meta のコンテンツポリシーと技術要件を確認する

互換性のクイックチェック

Horizon OS で動作します

機能	状態	備考
標準 Android ビュー	対応	TextView、RecyclerView など
Jetpack Compose	対応	Compose UI ツールキット全体
React Native	対応	標準の Android アプリケーションパスを使用
WebView	対応	Chromium ベース
メディア再生（ExoPlayer）	対応	動画と音声
ネットワーク（HTTP、WebSocket）	対応	Wi-Fi 接続
Room / SQLite	対応	ローカルデータベース
WorkManager	対応	バックグラウンドタスク
通知	対応	Horizon OS の通知パネル
Bluetooth（周辺機器）	対応	キーボード、マウス、ゲームパッド
Android アクセシビリティ API	対応	TalkBack 相当の機能を利用可能

制限あり、または利用不可

機能	状態	備考
電話機能 / SMS	利用不可	携帯電話無線機能がありません
NFC	利用不可	NFC ハードウェアがありません
GPS / 高精度位置情報	制限あり	Wi-Fi ベースの位置情報のみ
指紋認証 / BiometricPrompt	利用不可	代わりに Meta アカウント認証を使用してください
アプリが所有する複数パネル	制限あり	利用可能になったら、現行の公開されている複数パネルのガイダンスを使用してください
Google Play Services	利用不可	Meta の同等サービスまたは代替手段を使用してください
ARCore	利用不可	空間機能には Meta Spatial SDK を使用してください
マルチタッチジェスチャー	制限あり	コントローラーからのポインターは 1 つのみ

よくある問題と解決方法

問題	原因	解決方法
アプリの起動時にクラッシュする	Google Play Services の依存関係が不足している	GMS を削除するか、任意にします
ボタンが小さすぎてタップできない	タッチ対象が 48dp 未満	タップ対象の最小サイズを大きくします
キーボードが表示されない	カスタム入力フィールドが InputConnection を使用していない	標準の EditText または TextField を使用します
レイアウトが崩れる	固定サイズのレイアウトを前提としている	レスポンシブなビューまたは Compose レイアウトを使用します
アプリが利用できない権限を要求する	電話機能、NFC、その他の存在しないハードウェア	hasSystemFeature() チェックで保護します
禁止された権限が原因で APK が拒否される	ライブラリまたはプラグインが禁止された権限を暗黙的に追加した	aapt dump permissions your-app.apk を実行し、禁止リストを確認します
無効な署名が原因で APK が拒否される	v1 のみの方式で署名されている	AGP 7.0 以降では v2 署名がデフォルトです。古い AGP では署名設定に v2SigningEnabled = true を追加します

テストツール

• Meta Horizon OS Android Studio plugin：デバイス接続、デプロイ、Horizon OS 開発サポート
• Meta Spatial Simulator：Horizon OS 上の 2D Android アプリ向けデスクトップシミュレーション
• Android Studio、Gradle、ADB：標準的な Android のビルド、インストール、起動、logcat のワークフロー
• metavr：デバイスやアプリの操作に便利な、任意のコマンドラインツール

パフォーマンスに関する考慮事項

Meta VR デバイスは、厳しい熱制限のあるモバイルクラスのハードウェアを搭載しています。

• GPU：Qualcomm Adreno（モデルによって異なります）
• RAM：システムとアプリで共有する 6～12 GB
• 熱：高負荷が続くと、サーマルスロットリングが発生することがあります
• 2D UI では、過剰なオーバードローや複雑なシェーダーエフェクトを避けてください
• 消費電力を抑えるため、バックグラウンド処理を最小限にしてください
• 実際の使用状況を反映したデータ量（大きなリスト、画像など）でテストしてください

参考資料

• 互換性要件 -- ストア要件と API の互換性
• 入力の適応 -- タッチ操作をコントローラーやハンド入力に適応させる方法
• パネルレイアウト -- Horizon OS パネル向けのレスポンシブレイアウト
• Gradle の設定 -- ビルド設定とマニフェストのエントリー