Android XR is an extension of the Android platform and ecosystem. The Android XR SDK is designed to let you build XR apps using familiar Android frameworks and tools or using open standards such as OpenXR and WebXR. All compatible mobile or large screen apps will be available to install on XR headsets from the Play Store. Review the compatibility considerations to see if your app is compatible.
This guide explains the following areas:
- Selecting your development tools and technologies
- Designing apps for Android XR
- Configuring your app's manifest file
- App manifest compatibility considerations
- Understanding permissions for Android XR
- Ensuring Android XR app quality
- Packaging and distributing your app for Android XR
Select your development tools and technologies
When building an app for Android XR, you can choose from the following development platforms and technologies:
Jetpack XR SDK
The Jetpack XR SDK contains Android XR Jetpack libraries built to take advantage of the unique capabilities of XR devices. Start with this SDK if you want to do either of the following:
- Optimize or enhance an existing Android mobile or tablet app
- Build a new Android XR app using Android Studio and Jetpack
If you're already comfortable developing with Android Jetpack, the Jetpack XR SDK is a natural fit for you. It's designed to seamlessly integrate with those frameworks and libraries, and lets you use existing knowledge for building immersive XR experiences.
Learn more about developing with the Jetpack XR SDK.
Unity
Unity Engine is a real-time 3D development engine that lets artists, designers, and developers collaborate to create immersive and interactive experiences. Unity's Android XR support gives you a high level of control over the 3D experiences you develop, while benefitting from Unity's established OpenXR support and developer ecosystem.
If you already have an XR experience built with Unity or if you are familiar with Unity development, then start with this option.
Learn more about developing with Unity for Android XR.
OpenXR
OpenXR is a royalty-free, open standard that can be used for building high-performance, multi-platform XR experiences. Android XR supports OpenXR 1.0 and 1.1, and we are expanding the specification with new extensions for Android XR. Because Android XR is built on open standards, development tools that support OpenXR and Android should be compatible with Android XR.
Learn more about OpenXR support for Android XR.
WebXR
WebXR lets you build immersive experiences for the web. It provides access to VR and AR devices in compatible web browsers such as Chrome on Android XR.
Start with this option if you want to build an XR experience for the web or if you want to add XR capabilities to a web app. Existing WebXR experiences will also work on Android XR.
Learn more about building web apps with WebXR.
Design for XR
XR expands the design surface beyond traditional flat screens; you can design immersive experiences that blend physical and virtual reality. Whether you are building a brand new experience or adding immersive elements to an existing app, the design for Android XR guide can help you get started.
Configure your app's manifest file
As with other Android app projects, your Android XR app must have an AndroidManifest.xml file with specific manifest settings. The manifest file describes essential information about your app to the Android build tools, the Android operating system, and Google Play. See the app manifest overview guide for more information.
For XR differentiated apps, your manifest file must contain the following elements and attributes:
PROPERTY_ACTIVITY_XR_START_MODE property
The android:name="android.window.PROPERTY_ACTIVITY_XR_START_MODE" property
lets the system know that an activity should be launched in a specific mode when
the activity is started.
There are three possible values for this property:
XR_ACTIVITY_START_MODE_HOME_SPACE(Jetpack XR SDK only)XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED(Jetpack XR SDK only)XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED(OpenXR only)
XR_ACTIVITY_START_MODE_HOME_SPACE
(Apps built with the Jetpack XR SDK only)
Use this start mode to launch your app in Home Space. In Home Space, multiple apps can run side-by-side, so users can multitask. Any mobile or large screen Android app can operate in Home Space, as well as XR apps built using the Jetpack XR SDK.
<manifest ... >
<application ... >
<property
android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
android:value="XR_ACTIVITY_START_MODE_HOME_SPACE" />
<activity
android:name="com.example.myapp.MainActivity" ... >
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>
XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED
(Apps built with the Jetpack XR SDK only)
Use this start mode to launch your app in Full Space. In Full Space, only one app runs at a time, with no space boundaries, and all other apps are hidden.
<manifest ... >
<application ... >
<property
android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED" />
<activity
android:name="com.example.myapp.MainActivity" ... >
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>
XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED
(Apps built with OpenXR only)
Apps built with OpenXR launch in Full Space and must use
XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED start mode. Unmanaged full space
signals to Android XR the app uses OpenXR.
<manifest ... >
<application ... >
<property
android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED" />
<activity
android:name="com.example.myapp.MainActivity" ... >
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>
PackageManager features for XR apps
When you distribute apps through the Google Play Store, you
can specify required hardware or software features in the app manifest. The
uses-feature element allows the Play Store to appropriately filter apps
shown to users.
The following features are specific to XR apps.
android.software.xr.immersive
If your app targets the Android XR platform and only runs on platforms that support XR, set the value to true. If your app has some XR optimized features but can also run on non-XR devices, set the value to false.
Apps built with OpenXR or Unity are required to have this value set to true.
<uses-feature android:name="android.software.xr.immersive" android:required="true" />
android.hardware.xr.input.controller
This feature indicates that the app requires input from a high precision, 6DoF (degrees of freedom) motion controller to function correctly. If your app supports controllers and cannot function without them, set the value to true. If your app supports controllers but can operate without them, set it to false.
<uses-feature android:name="android.hardware.xr.input.controller" android:required="true" />
android.hardware.xr.input.hand_tracking
This flag indicates that the app requires high fidelity hand tracking to function correctly, including position, orientation, and velocity of joints in the user's hand. If your app supports hand tracking and cannot function without it, set the value to true. If your app supports hand tracking, but can operate without it, set it to false.
<uses-feature android:name="android.hardware.xr.input.hand_tracking" android:required="true" />
android.hardware.xr.input.eye_tracking
This flag indicates that the app requires high fidelity eye tracking for input to function correctly. If your app supports eye tracking for input and cannot function without it, set the value to true. If your app supports eye tracking for input, but can operate without it, set it to false.
<uses-feature android:name="android.hardware.xr.input.eye_tracking" android:required="true" />
App manifest compatibility considerations for mobile and large screen apps
As described in the PackageManager features for XR apps section, apps
declare that they use a feature by declaring it in a <uses-feature>
element in the app manifest. Some features, such as telephony or GPS, may not
be compatible with all devices.
Unsupported features
The Google Play store filters applications available for installation on a device by using the following Android feature declarations.
Camera Hardware
android.hardware.camera.autofocus
android.hardware.camera.capability.manual_post_processing
android.hardware.camera.capability.manual_sensor
android.hardware.camera.capability.raw
android.hardware.camera.concurrent
android.hardware.camera.external
android.hardware.camera.level.full
Connectivity
android.hardware.ipsec_tunnel_migration
Device Configuration
Form Factor Configuration
android.hardware.type.automotive
android.hardware.type.embedded
android.hardware.type.television
android.software.leanback_only
Input
android.software.input_methods
Location
Near Field Communication
Security Configuration and Hardware
android.hardware.se.omapi.uicc
android.hardware.biometrics.face
android.hardware.identity_credential
android.hardware.identity_credential_direct_access
android.hardware.keystore.limited_use_key
android.hardware.keystore.single_use_key
android.hardware.strongbox_keystore
Sensors
android.hardware.sensor.accelerometer_limited_axes
android.hardware.sensor.accelerometer_limited_axes_uncalibrated
android.hardware.sensor.ambient_temperature
android.hardware.sensor.barometer
android.hardware.sensor.gyroscope_limited_axes
android.hardware.sensor.gyroscope_limited_axes_uncalibrated
android.hardware.sensor.heading
android.hardware.sensor.heartrate
android.hardware.sensor.heartrate.ecg
android.hardware.sensor.hinge_angle
android.hardware.sensor.relative_humidity
android.hardware.sensor.stepcounter
android.hardware.sensor.stepdetector
Software Configuration
android.software.connectionservice
android.software.expanded_picture_in_picture
android.software.live_wallpaper
android.software.picture_in_picture
android.software.wallet_location_based_suggestions
Telephony
android.hardware.telephony.calling
android.hardware.telephony.cdma
android.hardware.telephony.data
android.hardware.telephony.euicc
android.hardware.telephony.euicc.mep
android.hardware.telephony.gsm
android.hardware.telephony.ims
android.hardware.telephony.mbms
android.hardware.telephony.messaging
android.hardware.telephony.radio.access
android.hardware.telephony.subscription
Virtual Reality (Legacy)
android.hardware.vr.headtracking
android.hardware.vr.high_performance
Widgets
Understand permissions for XR
Just like apps on mobile devices and other form factors, some capabilities offered by XR apps may require your app to declare permissions in your app's AndroidManifest file. In the case of dangerous permissions, your app may need to request runtime permissions. Read Permissions on Android and permission best practices for more in-depth information.
Permissions for XR features
The following permissions may be used by XR apps. All of the permissions in this section are considered dangerous permissions, so you must declare them in your app manifest and request them at runtime.
android.permission.EYE_TRACKINGUse cases requiring this permission
Representing the user's eye pose and orientation, for use with avatars.
Jetpack XR SDK features that require this permission
n/a
OpenXR extensions that require this permission
XR_ANDROID_avatar_eyes(deprecated)XR_ANDROID_eye_tracking(for coarse tracking)Unity features that require this permission
android.permission.EYE_TRACKING_COARSEUse cases requiring this permission
Representing the user's eye pose, status, and orientation, such as for use with avatars. Use this permission when low-precision eye tracking data is needed.
Jetpack XR SDK features that require this permission
n/a
OpenXR extensions that require this permission
XR_ANDROID_avatar_eyes(deprecated)XR_ANDROID_eye_tracking(for coarse tracking)Unity features that require this permission
android.permission.EYE_TRACKING_FINEUse cases requiring this permission
Eye gaze for selection, input, and interactions
Jetpack XR SDK features that require this permission
n/a
OpenXR extensions that require this permission
Unity features that require this permission
android.permission.FACE_TRACKINGUse cases requiring this permission
Tracking and rendering facial expressions
Jetpack XR SDK features that require this permission
n/a
OpenXR extensions that require this permission
Unity features that require this permission
android.permission.HAND_TRACKINGUse cases requiring this permission
Tracking hand joint poses and angular and linear velocities; Using a mesh representation of the user's hands
Jetpack XR SDK features that require this permission
OpenXR extensions that require this permission
Unity features that require this permission
android.permission.SCENE_UNDERSTANDINGUse cases requiring this permission
Light estimation; projecting passthrough onto mesh surfaces; performing raycasts against trackables in the environment; plane tracking; object tracking; working with depth for occlusion and hit testing; persistent anchors.
Jetpack XR SDK features that require this permission
OpenXR extensions that require this permission
Unity features that require this permission
android.permission.SCENE_UNDERSTANDING_COARSEUse cases requiring this permission
Light estimation; projecting passthrough onto mesh surfaces; performing raycasts against trackables in the environment; plane tracking; object tracking; persistent anchors.
Jetpack XR SDK features that require this permission
OpenXR extensions that require this permission
Unity features that require this permission
android.permission.SCENE_UNDERSTANDING_FINEUse cases requiring this permission
Depth texture
Jetpack XR SDK features that require this permission
n/a
OpenXR extensions that require this permission
Unity features that require this permission
Ensure Android XR app quality
To ensure your app provides a great user experience, review our Android XR app quality guidelines.
Package and distribute your app for Android XR
Android XR brings a wide variety of apps and experiences to XR headsets through Google Play. In the guide for packaging and distributing apps for Android XR, you'll find information on getting started with the Play Store and Play Console, publishing tracks, preparing Android app bundles, and app size restrictions.