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.

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>

<uses-native-library> OpenXR

(Apps built with OpenXR only)

OpenXR applications must declare the use of the native OpenXR library to successfully load its runtime. Without this declaration, the runtime will fail to load.


<manifest ... >

    <application ... >

    <uses-native-library android:name="libopenxr.google.so" android:required="true" />

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

android.software.xr.api.spatial

Apps that are built using the Jetpack XR SDK must include this feature in the app manifest. The value you set for the android:required attribute depends on your app's release track.

If your app bundles XR-differentiated features or content into an existing mobile APK and is published on the mobile release track, then you should set the android:required attribute to false. If your app is built specifically for XR-enabled devices and is published to the Android XR dedicated release track, then you should set the android:required attribute to true.

<uses-feature android:name="android.software.xr.api.spatial" android:required="true" />

android.software.xr.api.openxr

Apps that target the Android XR platform and are built with OpenXR or Unity must include this feature in the app manifest with the android:required attribute set to true.

Apps that use the Android XR Extensions Package for Unity version 1.0.0 or higher or the Unity OpenXR: Android XR Package version 0.5.0-exp.1 or higher don't have to add this element manually to the app manifest. These two packages will inject this element into the app manifest for you.

Devices may specify a version for this feature, which indicates the highest version of OpenXR supported by the device. The higher 16 bits represent the major number, and the lower 16 bits represent the minor number. For example, to specify OpenXR version 1.1, the value would be set to "0x00010001".

Apps can use the feature version to indicate a minimum version of OpenXR that the app requires. For example, if your app requires OpenXR version 1.1 support, declare the following feature:

<uses-feature android:name="android.software.xr.api.openxr"
    android:version="0x00010001"
    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.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 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.

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_COARSE

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

n/a

OpenXR Extensions

Unity Features

android.permission.EYE_TRACKING_FINE

Eye gaze for selection, input, and interactions.

Jetpack XR SDK

n/a

OpenXR Extensions

Unity Features

android.permission.FACE_TRACKING

Tracking and rendering facial expressions.

Jetpack XR SDK

n/a

OpenXR Extensions

Unity Features

android.permission.HAND_TRACKING

Tracking hand joint poses and angular and linear velocities; Using a mesh representation of the user's hands.

android.permission.SCENE_UNDERSTANDING_COARSE

Light estimation; projecting passthrough onto mesh surfaces; performing raycasts against trackables in the environment; plane tracking; object tracking; persistent anchors.

android.permission.SCENE_UNDERSTANDING_FINE

Depth texture.

Jetpack XR SDK

n/a

OpenXR Extensions

Unity Features

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.