expo-horizon

Expo Horizon：Expo SDK を Meta Quest に移行する

Software Mansion が提供する、expo-horizon パッケージを使用して Expo アプリに Meta Quest のサポートを追加するための本番環境向けガイドです。

このスキルにはドキュメントのコピーは含まれていません。 以下のタスクでは、最新のインストール手順、プラグインのオプション、API の概要、機能マトリックスを確認するため、必ずリンク先の公式 README または Meta のドキュメントページを webfetch してください。このスキルでは、エージェントが見落としがちな判断ツリー、重要なルール、わかりにくい注意点のみを取り上げます。

判断ツリー

What do you need to do?
│
├── Starting from scratch or adding Quest support to an existing Expo app?
│   └── Follow the "Setup Workflow" below (do NOT auto-install location or
│       notifications packages) and webfetch: expo-horizon-core README
│       ├── Install expo-horizon-core
│       ├── Configure the config plugin (horizonAppId, panel size, supportedDevices)
│       ├── Add quest/mobile build scripts
│       ├── Add runtime device detection (isHorizonDevice, isHorizonBuild)
│       └── Detect expo-location / expo-notifications, then ASK before migrating
│
├── Need location services on Quest?
│   └── Webfetch: expo-horizon-location README
│       ├── Replace expo-location with expo-horizon-location
│       ├── Review the feature support matrix
│       └── Guard unsupported calls (heading, geocoding, geofencing, background)
│
├── Need push notifications on Quest?
│   └── Webfetch: expo-horizon-notifications README
│       ├── Replace expo-notifications with expo-horizon-notifications
│       ├── Configure horizonAppId in expo-horizon-core
│       ├── Use getDevicePushTokenAsync (Expo Push Service is not supported)
│       └── Skip badge counts (not supported on Quest)
│
└── Need to build, run, or publish for Quest?
    └── Webfetch: expo-horizon-core README (build variants) + Meta docs below
        ├── Build variants: questDebug, questRelease, mobileDebug, mobileRelease
        ├── Meta Quest Developer Hub (device management, sideloading)
        └── Meta Horizon Store manifest requirements

セットアップのワークフロー（既存の Expo アプリへの Quest サポートの追加）

ユーザーから Meta Quest のサポート追加を依頼された場合は、以下の手順を順番どおりに実行してください。手順 2 と 3 を 1 つのインストールコマンドにまとめないでください。兄弟パッケージのインストールには、ユーザーによる明示的な確認が必要です。

1. expo-horizon-core をインストールして設定します。

   • npx expo install expo-horizon-core を実行します。
   • 設定プラグインの値を書き込む前に、ユーザーに確認します。 ユーザーがカスタム値を貼り付けるか、デフォルト値を一度に承認できるよう、すべてのオプションを 1 つのプロンプトにまとめて提示します。各オプションは、次の例のようにデフォルト値を角括弧で囲み、1 行ずつ表示します。

     app.json に expo-horizon-core 設定プラグインを追加します。各値を確認または変更してください（Enter キーを押すか、「default」と返信すると、角括弧内のデフォルト値を使用します）。

     • supportedDevices [quest2|quest3|quest3s] — アプリがサポートする Quest デバイスをパイプ区切りで指定します（Meta Horizon Store への申請に必須）。
     • horizonAppId [空欄] — Meta Horizon アプリケーション ID です。プッシュ通知を利用する予定がなければ空欄のままにしてください。expo-horizon-notifications でデバイスのプッシュトークンを発行する際に必要です。
     • defaultWidth [1024dp] — デフォルトのパネル幅です。省略する場合は空欄のままにしてください。
     • defaultHeight [640dp] — デフォルトのパネル高さです。省略する場合は空欄のままにしてください。幅または高さを設定する場合は、Expo の orientation と一致させてください（幅の広いパネルでは "landscape" を使用します）。
     • disableVrHeadtracking [false] — true に設定すると、マニフェストへの android.hardware.vr.headtracking エントリーの追加を省略します。
     • allowBackup [false] — Meta は機密データに対して false を推奨しています。Quest ビルドで Android のバックアップが必要な場合にのみ true に設定してください。

   • ユーザーの返信後にのみプラグイン設定を書き込みます。ユーザーが空欄のままにしたオプションは省略し、パッケージ独自のデフォルト値を適用します（horizonAppId、defaultWidth、defaultHeight に空文字列を設定しないでください）。
   • package.json に quest / mobile のビルドスクリプトを追加します。
   • npx expo prebuild --clean を実行します。
   • 確認を求める前に、expo-horizon-core README を webfetch し、最新のオプション名とデフォルト値を確認してください。上記のデフォルト値は、リリースによって変更される可能性があります。

2. 既存の位置情報／通知パッケージを検出します。horizon の同等パッケージはまだインストールしないでください。

   • プロジェクトの package.json を読み取ります。
   • dependencies と devDependencies に expo-location と expo-notifications があるか確認します。
   • どちらもない場合は、このワークフローの残りを省略します。ユーザーには移行作業がありません。

3. 検出されたパッケージごとに、移行する前にユーザーに確認します。

   • expo-location が見つかった場合は、次のように尋ねます。

     "プロジェクトで expo-location が見つかりました。Meta Quest で位置情報を利用できるように、expo-horizon-location に置き換えますか？（Quest には GPS、方位、ジオコーディング、ジオフェンス機能がありません。サポートされていない呼び出しは ExpoHorizon.isHorizonDevice でガードする必要があります。）"

   • expo-notifications が見つかった場合は、次のように尋ねます。

     "プロジェクトで expo-notifications が見つかりました。Meta Quest でプッシュ通知を利用できるように、expo-horizon-notifications に置き換えますか？コアの設定プラグインに horizonAppId が必要で、Expo Push Service ではなく Meta のプッシュサービスを使用します。また、バッジ数と getExpoPushTokenAsync はサポートされていません。"

   • 両方のパッケージが存在する場合は、質問をまとめて提示します。
   • これらのパッケージのインストールや編集を行う前に、明示的な回答を待ちます。

4. ユーザーの確認後に限り、承認されたパッケージの移行を行います。

   • Horizon 版をインストールします（npx expo install expo-horizon-location または expo-horizon-notifications）。
   • 元のパッケージをアンインストールします（npm uninstall expo-location または expo-notifications）。
   • すべての import 文を Horizon パッケージ名に更新します。
   • 通知の場合は、expo-horizon-core プラグインの設定で horizonAppId が設定されていることを確認し、expo-horizon-notifications を plugins 配列に追加します。
   • もう一度 npx expo prebuild --clean を実行します。
   • 関連する README（location または notifications）を Webfetch して、機能サポートの全一覧を確認し、サポートされていない呼び出しを ExpoHorizon.isHorizonDevice でガードします。

5. ユーザーが移行を拒否した場合は、元のパッケージをそのまま残し、機能 X（location / notifications）は移行するまで quest ビルドでは動作しないことを概要に記載します。

重要なルール

• 必ず最初に expo-horizon-core をインストールしてください。 これは他のすべての expo-horizon パッケージに必要で、他のパッケージが依存する quest／mobile ビルドフレーバーを設定します。

• expo-horizon-location や expo-horizon-notifications を自動インストールしないでください。 Quest 対応を追加する際は、package.json 内の既存の expo-location／expo-notifications 依存関係を検出し、それぞれを移行するかどうかユーザーに確認します。ユーザーが明示的に承認したパッケージのみをインストールして設定してください。上記のセットアップワークフローを参照してください。

• quest ビルドバリアントは Meta Quest デバイスでのみ使用してください。 標準的な Android スマートフォンで questDebug または questRelease ビルドを実行することはサポートされておらず、予期しない動作が発生します。

• 設定プラグインで supportedDevices を設定してください。 Meta Horizon Store への申請に必要です。パイプ区切りの値を使用します。"quest2|quest3|quest3s"。

• プラグイン設定を変更した後は、npx expo prebuild --clean を実行してください。 設定プラグインは prebuild 時にネイティブプロジェクトファイルを変更します。古いネイティブプロジェクトには変更が反映されません。

• パッケージだけでなく、import 文も置き換えてください。 expo-location または expo-notifications から移行する場合は、すべての import 文を新しいパッケージ名（expo-horizon-location、expo-horizon-notifications）を使うように更新します。

• Quest には GPS、磁気センサー、ジオコーダーがありません。 方位、ジオコーディング、逆ジオコーディング、ジオフェンスなどの機能は Quest では利用できません。これらの呼び出しは ExpoHorizon.isHorizonDevice または ExpoHorizon.isHorizonBuild でガードしてください。

• プッシュ通知には horizonAppId が必要です。 これが設定されていない場合、Quest デバイスでは getDevicePushTokenAsync が有効なトークンを返しません。Quest では getExpoPushTokenAsync ではなく getDevicePushTokenAsync を使用してください。返された { type: 'horizon', data } トークンをバックエンドに送信し、Meta のプッシュサービスを通じて配信します。

• isHorizonDevice と isHorizonBuild の使い分け。 実行時のハードウェア確認（物理 Quest の検出）には isHorizonDevice を使用します。ビルド時の機能切り替え（どのネイティブコードがコンパイルされたか）には isHorizonBuild を使用します。

• Expo Go はサポートされていません。 npx expo prebuild を使ってカスタム開発ビルドを作成する必要があります。

公式リファレンス

HTML 表示でソースが表示されない場合は、必ず raw markdown（raw.githubusercontent.com/...）を webfetch してください。raw URL が信頼できるソースです。

トピック	公式ソース
リポジトリの概要とパッケージ一覧	expo-horizon README
インストール、config plugin のオプション、ランタイム API、ネイティブモジュールへのアクセス	expo-horizon-core README
位置情報の移行、制限事項、機能サポートマトリックス	expo-horizon-location README
プッシュ通知の移行、トークンの種類、機能サポートマトリックス	expo-horizon-notifications README
3 つのパッケージすべてを組み込んだサンプルアプリ	expo-horizon example README
パネルサイズのガイドライン（dp 値、向き、レターボックス表示）	Meta Panel Sizing
公開用 Meta Horizon Store マニフェストのチェックリスト	Publish Mobile Manifest
デバイス管理、キャスト、サイドローディング、ADB	Meta Quest Developer Hub
Meta のプッシュサービスを介したサーバー側プッシュ配信	Horizon OS push notifications