Overview of building for Android XR

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.

Note: If you use one of the Android XR packages for Unity, you don't need to add these elements or attributes manually. The Unity packages create the manifest for your app based on your project and build settings.

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.

Note: If you use one of the Android XR packages for Unity, your app will also launch in Full Space. However, you don't need to add this to your manifest manually. The Unity packages create the manifest for your app based on your project and build settings.

<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.

Note: 6DoF motion controllers are a pair of hardware controllers, one for each hand. Each controller is tracked independently in space through six degrees of freedom - both linear and rotational movements. These controllers typically have several hardware buttons, including a trigger as well as haptic feedback.

<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.

Note: This flag is not required for detecting basic gestures such as pinching, poking, aiming, and gripping.

<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" />

Note: Hand tracking and eye tracking are privacy-sensitive input methods and require the apps to request special permissions. See Understand permissions for XR on this page for more information on declaring permissions.

App manifest compatibility considerations for mobile and large screen apps

Note: This section applies only to mobile or large screen apps that haven't been optimized for XR. By default, these kinds of Android apps will run on Android XR. However, if your app requires one or more of the features in this section, the app will not be shown in the Play Store on Android XR.

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.

Note: To get a listing of the features that are enabled for a device, run adb shell pm list features.

Unsupported features

The Google Play store filters applications available for installation on a device by using the following Android feature declarations.

Caution: If your app requires a feature that is not supported on the device, then that app won't be available for installation from the Play Store for XR devices. If your app uses the feature, but is designed to run without it, you should set android:required="false". For example, <uses-feature android:name="android.hardware.location.gps" android:required="false" />.

Camera Hardware

android.hardware.camera.ar

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.flash

android.hardware.camera.level.full

Connectivity

android.hardware.ethernet

android.hardware.uwb

android.hardware.ipsec_tunnel_migration

Device Configuration

android.hardware.ram.low

Form Factor Configuration

android.hardware.type.automotive

android.hardware.type.embedded

android.hardware.type.pc

android.hardware.type.television

android.hardware.type.watch

android.software.leanback

android.software.leanback_only

android.software.live_tv

Input

android.hardware.consumerir

android.software.input_methods

Location

android.hardware.location.gps

Near Field Communication

android.hardware.nfc

android.hardware.nfc.ese

android.hardware.nfc.hce

android.hardware.nfc.hcef

android.hardware.nfc.uicc

android.hardware.nfc.beam

Security Configuration and Hardware

android.hardware.se.omapi.ese

android.hardware.se.omapi.sd

android.hardware.se.omapi.uicc

android.hardware.biometrics.face

android.hardware.fingerprint

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.light

android.hardware.sensor.relative_humidity

android.hardware.sensor.stepcounter

android.hardware.sensor.stepdetector

Software Configuration

android.software.backup

android.software.connectionservice

android.software.expanded_picture_in_picture

android.software.live_wallpaper

android.software.picture_in_picture

android.software.telecom

android.software.wallet_location_based_suggestions

Telephony

android.hardware.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

android.software.sip

android.software.sip.voip

Virtual Reality (Legacy)

android.hardware.vr.headtracking

android.hardware.vr.high_performance

android.software.vr.mode

Widgets

android.software.app_widgets

Understand permissions for XR

Just like apps on mobile devices and other form factors, some functionality 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_TRACKING

Use cases requiring this permission

Representing the user's eye pose and orientation, for the purposes of avatars

Jetpack XR SDK features that require this permission

n/a

OpenXR extensions that require this permission

XR_ANDROID_avatar_eyes

Unity features that require this permission

Android XR: AR Face

android.permission.EYE_TRACKING_FINE

Use cases requiring this permission

Eye gaze input and interactions

Jetpack XR SDK features that require this permission

n/a

OpenXR extensions that require this permission

XR_EXT_eye_gaze_interaction

Unity features that require this permission

Eye Gaze Interaction

android.permission.FACE_TRACKING

Use 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

XR_ANDROID_face_tracking

Unity features that require this permission

XRFaceTrackingFeature

android.permission.HAND_TRACKING

Note: This permission is not required for detecting basic gestures such as pinching, poking, aiming, and gripping.

Use 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

n/a

OpenXR extensions that require this permission

XR_ANDROID_hand_mesh

XR_EXT_hand_tracking

Unity features that require this permission

XR Hands

XRHandMeshFeature

android.permission.SCENE_UNDERSTANDING

Use 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

Plane Tracking

Hit Testing

Anchor Persistence

OpenXR extensions that require this permission

XR_ANDROID_anchor_persistence

XR_ANDROID_depth_texture

XR_ANDROID_light_estimation

XR_ANDROID_composition_layer_passthrough_mesh

XR_ANDROID_raycast

XR_ANDROID_trackables

XR_ANDROID_trackables_object

Unity features that require this permission

XRAnchorFeature

XRDepthTextureFeature

XRLightEstimationFeature

XRPassthroughFeature

XRTrackableFeature

XRObjectTrackingFeature

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.