portal

Portal

このスキルは、Meta の Portal デバイスファミリーを対象とした Android アプリの開発向けです。Portal デバイスは販売終了しています（2022 年末に販売停止）が、現在は ADB が有効になっているため、所有者は独自のアプリをサイドロードできます。

ハードウェア：Google Mobile Services を含まない改変版 AOSP を搭載した、Snapdragon ベースの Android タブレットおよび TV スティックです。複数のモデルがあり、すべてタッチ操作または TV 向けです。デバイスに応じて、minSdkVersion は 28（Android 9）または 29（Android 10）です。

このスキルは metavr（Meta VR CLI）と併用します。まずこれをインストールしてください。どこでも素の adb の代わりに metavr adb を使用してください。ワンライナーでのインストール方法（npx 経由）、MCP をエディターに導入する設定、Portal 関連コマンドの一覧については、resources/metavr.md を参照してください。より詳しいリファレンスが必要な場合は、完全版の metavr-cli スキルも同じリポジトリから読み込めます。

コードを書く前に必ず読むべき厳守事項

覚えることが少しだけなら、次の項目を覚えてください。いずれも、Portal アプリで頻繁に発生するバグの原因です。

1. Google モバイルサービスは使用できません。 Play Services、Firebase、FCM、Play Billing、Google Sign-In、Google Maps SDK、AdMob、ML Kit は使用できません。GMS に強く依存するアプリは起動時にクラッシュします。GMS に依存しない代替手段を選んでください。詳しくは resources/app-requirements.md を参照してください。
2. minSdkVersion ≤ 28 が必須です（Portal ハードウェアの上限は API 29 です）。新規アプリでは、targetSdkVersion 29 が最も安全な既定値です。既存アプリの移植では、29 より高い targetSdkVersion も通常は問題なく動作します。targetSdk = 36 で実証済みです。具体的なランタイムの問題が確認されない限り、既存アプリの target SDK を下げることに時間を費やさないでください。
3. ランチャーの intent-filter が必須です。 タッチデバイスでは MAIN + LAUNCHER、Portal TV では MAIN + LEANBACK_LAUNCHER が必要です。DEFAULT カテゴリーは不要です（Portal での実証済み。MAIN + LAUNCHER のみのアプリもホーム画面のタイルグリッドに表示されます）。これらのいずれも指定しないと、アプリはインストールされますが、ホーム画面に表示されません。
4. アプリアイコンには、フォールバック用に mipmap-xxxhdpi/ の PNG を含める必要があります。 ランチャーアクティビティに、タッチデバイスでは android:icon、TV では android:banner を指定してください。アダプティブアイコン（mipmap-anydpi-v26/）や他の密度の PNG も同梱できます。Portal のランチャーは、アダプティブアイコンの XML を描画できない場合に mipmap-xxxhdpi の PNG に正しくフォールバックします。アダプティブアイコンのみ（PNG のフォールバックなし）のアプリは、Portal でアイコンが表示されません。
5. 連絡先 API はありません。アカウント／認証情報 API もありません。 READ_CONTACTS は拒否されます。アカウントプロバイダーは何も返しません。 5a. 基本的なマイク録音は動作しますが、遠距離音声用／ビームフォーミング対応のマイクアレイは使用できません。 標準の RECORD_AUDIO は AudioRecord ストリームを開き、handset-mic（単一チャンネルのマイク）から実際の音声を取得します。「Hey Portal」のウェイクワードで使用される遠距離音声用のビームフォーミングアレイは、Meta の署名付きネイティブ権限（com.facebook.alohasdk.permission.RECORD_AUDIO_PRIVILEGED）によって制限されており、サイドロードしたアプリでは使用できません。そのため、基本的な音声機能は動作しますが、サイドロードしたアプリでのウェイクワード検出や、室内の離れた場所から高品質な音声を拾う機能は動作しません。詳しくは resources/app-requirements.md § マイク録音 を参照してください。
6. スマートフォン向けではなく、テーブル上で使うタッチ UI にしてください。 Portal はカウンターやスタンドに置き、ユーザーは 50〜100 cm 離れた場所から操作します。タッチターゲットは 64 dp 以上（主要な操作では 96 dp）、本文テキストは 16 sp 以上（Portal+ では 18 sp）、横向き優先にしてください。Portal のデザインシステム全体（タイポグラフィ、間隔、パレット、WCAG コントラスト比、TalkBack のルール）については resources/design-guidelines.md を参照してください。Jetpack Compose アプリ向けの resources/compose-theme.md は、これらのルールを Color.kt／Theme.kt／Type.kt に組み込んだ、そのままコピーして使えるテーマのスターターです。
7. 画面上部の約 64 dp を空けてください（上部のコンテンツがキャンバスの端から 64 dp 以内にある場合のみ）。Portal には、画面上部に常時表示されるシステムオーバーレイがあります。戻る／ホームボタン（左上）とWi-Fi／ステータス（右上）が表示されます。これはアプリのコンテンツの上に重なり、自動的にセーフエリアのインセットは設定されません。端に沿う上部 UI（エッジツーエッジのツールバー、固定ヘッダー、画面いっぱいに表示するモーダル）は、その下に隠れてしまいます。上部のコンテンツがキャンバスの端から自然に 80 dp 以上下にあるアプリでは、変更は不要です。オーバーレイのピルは白色です。そのため、上部領域の背景が明るいアプリでは、インセットを設定した後も暗いスクラムが必要です。詳しくは resources/app-requirements.md § システムオーバーレイ（画面上部）を参照してください。

デバイス一覧

デバイス	minSdkVersion	接続
Portal（第 1 世代および第 2 世代）	28 / 29	USB-C（背面）
Portal Mini	29	USB-C（背面）
Portal+（第 1 世代および第 2 世代）	28 / 29	USB-C（背面）
Portal Go	29	USB-C（背面のゴムカバーの下）
Portal TV	29	USB-C

すべての機種に対応する場合は、minSdkVersion 28 を設定してください。第 1 世代の Portal／Portal+ に対応する必要がなければ、29 を指定できます。

クイックスタート

まずはツールチェーンを用意しましょう。手作業で探し回る必要はありません。 ビルドにはホストマシンに2つの要素が必要です。Gradle／AGPを実行するJDKと、Android SDKです。SDKはGoogleのandroid CLIを使ってインストールしてください。ファイルシステム内を探し回ってSDKを見つける必要はありません。JDKについては、Android Studioがインストールされている場合はJAVA_HOMEをAndroid Studioに同梱されているJBRに設定し、そうでない場合はTemurin 17をインストールしてください。android CLIでインストールできるのはSDKのみです。JDKは提供されません。 詳しい手順については、resources/android-sdk-setup.mdをご覧ください。

# 1) Get a JDK 17 (one-time, host machine — Gradle / AGP run on it; the `android` CLI does NOT install one)
#    If Android Studio is installed, reuse its bundled JBR (no install needed):
#      export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
#    Otherwise install Temurin 17:
#      brew install --cask temurin@17 && export JAVA_HOME="$(/usr/libexec/java_home -v 17)"
java -version   # should report 17.x (or 21.x if using Android Studio JBR)

# 2) Install Google's `android` CLI (it manages the SDK), then install the SDK packages
#    macOS:   brew tap android/tap && brew install android-cli
#    Any OS:  curl -fsSL https://dl.google.com/android/cli/latest/darwin_arm64/install.sh | bash   (see § 1 for other OSes)
#    Windows: winget install --id Google.AndroidCLI
android update                                     # keep the CLI current
#    Install the SDK. For a new project: API 28 + 29. For porting, also install whatever compileSdk needs (often 35/36).
android sdk install platforms/android-28 platforms/android-29 platform-tools build-tools/34.0.0
export ANDROID_HOME="$HOME/Library/Android/sdk"   # macOS — Linux uses ~/Android/Sdk

# 3) Install metavr (one-time, host machine — standalone binary, no Node.js needed)
#    See resources/metavr.md for all install options (incl. npx without install) and MCP-into-your-editor setup.
curl -fsSL https://developers.meta.com/horizon/install-cli/ | sh   # macOS/Linux
# Windows (PowerShell): iwr -useb https://developers.meta.com/horizon/install-cli/windows/ | iex
metavr --version
# (or with Node.js 16+: npx -y metavr --version, no install required)

# 4) Enable ADB on the Portal
#    Portal: Settings → Debug → ADB Enabled. Enter PIN if prompted.
#    Connect USB-C. Tap "Allow" on the device the first time you connect.

# 5) Verify
metavr device list
# Should list one Portal device. Example: 819PGF02P010SL23  device  Portal  aloha
# (or npx -y metavr device list)

# 6) Build + install + launch
#    No ./gradlew in the project? Bootstrap the wrapper first — see resources/android-sdk-setup.md § 0a.
./gradlew assembleDebug
metavr app install -r app/build/outputs/apk/debug/app-debug.apk   # -r/--replace reinstalls, keeping data
metavr app launch com.example.myapp                               # or: metavr adb shell am start -n com.example.myapp/.MainActivity
# (or prefix with npx -y if you use the npm distribution instead of the standalone binary)

metavr device listにデバイスが表示されない場合は、PortalでADB Enabledをもう一度タップしてください。この切り替えはUSB接続とタイミングが競合することがあります。

ビルド設定

app/build.gradle.kts：

android {
    compileSdk = 35

    defaultConfig {
        minSdk = 28
        targetSdk = 29
    }
}

compileSdk = 35（または最新の値）で問題ありません。Portalとの互換性で重要なのは、min／targetの値です。

マニフェスト

ランチャーエントリはデバイスの種類によって異なります。

タッチデバイス（Portal、Portal Mini、Portal+、Portal Go）：

<activity
    android:name=".MainActivity"
    android:icon="@mipmap/ic_launcher"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

Portal TV（android:iconの代わりにLEANBACK_LAUNCHERとandroid:bannerを使用します）：

<activity
    android:name=".MainActivity"
    android:banner="@drawable/banner"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
</activity>

これらがない場合、アプリはインストールされても表示されません。1つのAPKで両方の種類に対応するには、同じアクティビティに両方のインテントフィルターを宣言してください。

使用できる権限／できない権限

機能	状況
カメラ	通常のCAMERA権限
マイク	通常のRECORD_AUDIO権限
スピーカー	権限は不要
Bluetooth	通常のBLUETOOTH*権限
ネットワーク	通常のINTERNET／ACCESS_NETWORK_STATE権限
タッチ／キーボード入力	権限は不要
ストレージへの書き込み	通常のWRITE_EXTERNAL_STORAGE（Android 9のモデル）
ストレージの削除（アプリ間）	アプリが所有するもののみ。それ以外の場合は、metavr adb shell rmを使用するか、ファイルマネージャーアプリをインストールしてください
連絡先（READ_CONTACTS）	**利用できません。**実行時に拒否されます
デバイスアカウント（AccountManager）	**利用できません。**アカウントプロバイダーから何も返されません

Smart Camera SDK（バイナリは準備中）

Portalのカメラは、顔／身体のトラッキング、フレーミング、人物をフレーム内に収める自動パン・ズームを担うシステムのSmart Cameraサービスによって制御されます。この動作を得るために、アプリがCamera2でカメラを直接制御することはありません。Smart Cameraサービスからセッションをリクエストし、ModeSpec（自動フレーミング、デスク用フレーミング、会議用フレーミング、固定クロップなど）を渡します。

単独で使用できるSmart Camera SDKを開発中です。予定されているGradle座標はcom.facebook.portal:smartcamera:1.1.+です。バイナリがリリースされるまでは、APIの概要についてresources/smart-camera-sdk.mdをご覧ください。構成、ModeSpecの各モード、SmartCameraControlConnectionFactoryのエントリーポイントは同じです。

標準のCamera2 APIを通じて、未加工のビデオフレームも引き続き利用できます。Smart Camera SDKはピクセルではなく、フレーミングを制御するためのものです。

デバッグの流れ

metavr adb logcat                                  # full logcat
metavr adb logcat *:E                              # errors only
metavr adb logcat -s AndroidRuntime DEBUG libc     # crash signals
metavr log -c                                      # clear the log buffer (NOT `metavr adb logcat -c` — that flag is rejected)
metavr adb shell dumpsys activity activities       # what's running
metavr app clear com.example.myapp                 # wipe app data (or: metavr adb shell pm clear <pkg>)
metavr app uninstall com.example.myapp             # uninstall
metavr capture screenshot -o screen.png            # save a PNG of the screen

その他のパターンやよくある失敗（アイコンが表示されない、インストール後にアプリが表示されない、初回起動時にアプリがクラッシュするなど）については、resources/debugging.mdをご覧ください。

リソース

• resources/metavr.md — metavr の概要、1 行でのインストール、エディターへの MCP の導入、Portal 関連コマンド
• resources/device-setup.md — ユーザー向けのデバイス準備手順の詳細
• resources/android-sdk-setup.md — JDK 17、Android CLI、SDK プラットフォーム／build-tools のインストール
• resources/native-toolchain.md — NDK／CMake／Ninja のセットアップ（プロジェクトにネイティブコードが含まれる場合に使用します。source.properties だけでは不十分なため、詳細な検証要件についても説明します）
• resources/app-requirements.md — マニフェスト、アイコン、GMS なし、デザインチェックリスト（詳細）
• resources/porting-existing-apps.md — 既存の Android アプリを Portal に移植するための手引き（GMS なしのバリアント、ネイティブコード、よくある失敗）
• resources/design-guidelines.md — タイポグラフィ、間隔、色、アクセシビリティ、TV／D-pad、Smart Camera の UX
• resources/compose-theme.md — コピーして使える Jetpack Compose のテーマスターター（ダークテーマの強制、Portal の配色、同梱の Inter タイポグラフィ、タッチターゲット）と GMS なしの場合のフォント修正
• resources/smart-camera-sdk.md — Smart Camera API の概要（バイナリは準備中）
• resources/debugging.md — metavr adb の logcat／スクリーンショット／dumpsys のパターン
• resources/sample-prompts.md — Claude／Cursor などに入力するためのプロンプト例