Develop

Create a new app

Updated: Sep 15, 2026
Use this guide to create a new Android app for Meta VR devices. Start from the template, configure the required manifest settings, then adapt and test your app before adding platform features.

Start from the template

Horizon OS template running in Meta Spatial Simulator
We recommend starting with the Horizon OS template. It gives you a project that already declares the Horizon OS requirements, and it has two routes to the same starter — a single-activity Jetpack Compose app:
The template can be run in Meta Spatial Simulator or on your device.

Manifest requirements

If you don’t use the template, make sure your AndroidManifest.xml declares the following Horizon OS tags and metadata so your app launches and displays correctly on Meta VR devices:
AreaManifest declarationWhy it matters
Supported devices
<meta-data android:name="com.oculus.supportedDevices" android:value="quest2|questpro|quest3|quest3s" />
Declares supported Quest devices
Default window size
android:defaultWidth="1024dp" android:defaultHeight="640dp" inside <layout>
Initial size of your resizable app window
Minimum window size
android:minWidth="360dp" android:minHeight="225dp" inside <layout>
Optional. Set a floor only if your layout breaks below a certain size.
Orientation and display
android:screenOrientation and window metadata
Handles window resizing and immersive display
Example manifest snippet:
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <meta-data
            android:name="com.oculus.supportedDevices"
            android:value="quest2|questpro|quest3|quest3s" />
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <layout
                android:defaultWidth="1024dp"
                android:defaultHeight="640dp" />
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Eye tracking permissions and Look and Pinch

When using Look and Pinch, don’t request eye tracking permissions—the system handles gaze and sends standard touch events. Remove these if present:
<!-- Do NOT include -->
<uses-permission android:name="com.oculus.permission.EYE_TRACKING" />
<uses-permission android:name="horizonos.permission.EYE_TRACKING" />
An app that requests them fails the Look and Pinch review. Hybrid apps that need eye tracking in immersive mode must declare the permission but only request it at runtime when the immersive activity launches. See Look and Pinch for 2D apps.

Style your app with our UI set

After configuring the manifest, style your app with components designed to look good on Meta VR devices. Our UI set is built for resizable app windows, controller and hands input, and accessibility:
  • Buttons, Cards, Controls, Dialogs, Dropdowns, Inputs, Sliders, Tooltips, Navigation items — all handle focus, hover, and resizing for you
  • Single import from the component library, no custom panel logic needed
Quick start: add the library and use Button, Card, Dialog in your Compose layout. See Component library overview for install and full component list.

Test in Meta Spatial Simulator

You don’t need a physical device for the first iteration.
Meta Spatial Simulator is available in the Meta VR Android Studio Plugin or Meta VR CLI and renders your panel in a VR environment.
To test with the plugin, open your app, select the Meta Spatial Simulator device, and click Run.
To test from the command line, download and start the simulator, then install and launch your APK:
metavr ssim download
metavr ssim start
metavr app install path/to/app.apk
metavr app launch your.package.name
Meta VR CLI does not build your app. Build the APK with Android Studio or Gradle before you install it. Both workflows launch the same APK you would install on a physical device and let you verify resizing, input, and window configuration. For complete setup and debugging guidance, see Test on simulator.

Follow the design guidelines

Our design guidelines ensure your app is usable on device and passes review. Short version:
  • Respect default and minimum panel sizes—don’t assume a static layout. Users can resize your windows at will, so design the content to reflow.
  • Support both controllers and hands, keep touch targets at least 48dp, and provide visual indications for hover effects.
  • Keep text readable at distance, use high contrast, avoid small fonts
For the full checklist, see Design requirements.

Enhance your app

After your new app runs on Meta VR devices, explore these features for VR:

Look and Pinch

Look and Pinch uses your app’s UI structure, text, and buttons to deliver standard input events. Test your app with Meta Spatial Simulator and follow the Look and Pinch design guidance, including using touch targets that are at least 48dp.
For special scenarios such as hover effects, use the Gaze SDK for Jetpack Compose.
When you’re ready, test on a device and publish your app to the store.

Troubleshooting

Gradle uses the wrong JDK

Android Studio uses its own Gradle JDK setting for project sync. If the Horizon OS Template cannot sync, open Settings > Build, Execution, Deployment > Build Tools > Gradle and set Gradle JDK to JDK 17. Sync the project again.
If a command-line build that uses Gradle 8.7 fails on JDK 25, set JAVA_HOME to your JDK 17 installation directory before running the Gradle wrapper again.
Meta
English (US)
© 2026 Meta