Comienza a usar OpenXR para Android XR

Dispositivos de realidad extendida correspondientes

Esta guía te ayuda a crear experiencias para estos tipos de dispositivos de realidad extendida.

Más información sobre los tipos de dispositivos de realidad extendida →

Visores de realidad extendida

Lentes de realidad extendida con cable

Más información sobre los tipos de dispositivos de realidad extendida →

Antes de comenzar a compilar con extensiones de OpenXR compatibles o con un motor compatible, revisa la configuración del manifiesto y los requisitos de permisos en las siguientes secciones para asegurarte de que tu app esté configurada para el desarrollo de XR.

Configura el archivo de manifiesto de tu app

Al igual que con otros proyectos de apps para Android, tu app para Android XR debe tener un archivo AndroidManifest.xml con parámetros de configuración de manifiesto específicos. El archivo de manifiesto describe información esencial sobre tu app para las herramientas de compilación de Android, el sistema operativo Android y Google Play. Para obtener más información, consulta la guía de descripción general del manifiesto de la app.

Nota: Si bien las apps creadas con Unity, Unreal Engine o Godot para Android XR se compilan sobre OpenXR, no es necesario que agregues la mayoría de estos elementos o atributos del manifiesto de forma manual si usas los complementos oficiales de Android XR para esos motores. Los complementos del motor y los ajustes predeterminados de exportación configuran el manifiesto de tu app según la configuración del proyecto y de la compilación.

En el caso de las apps diferenciadas para XR, tu archivo de manifiesto debe contener los siguientes elementos y atributos:

Propiedad PROPERTY_XR_ACTIVITY_START_MODE

La propiedad android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" permite que el sistema sepa que se debe iniciar una actividad en un modo específico cuando se inicia la actividad.

Esta propiedad tiene los siguientes valores:

• XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED (solo OpenXR)

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

Las apps compiladas con OpenXR se inician en el espacio completo y deben usar el modo de inicio XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED. El espacio completo no administrado indica a Android XR que la app usa OpenXR.

Nota: Si usas uno de los paquetes de Android XR para Unity, tu app también se iniciará en el espacio completo. Sin embargo, no es necesario que lo agregues a tu manifiesto de forma manual. Los paquetes de Unity crean el manifiesto para tu app según la configuración de tu proyecto y compilación.

<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" />
               <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
           </intent-filter>
       </activity>
   </application>
</manifest>

Propiedad PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED

La propiedad android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED" indica que la aplicación se debe iniciar con un tipo específico de límite. Tu app debe especificar XR_BOUNDARY_TYPE_LARGE si está diseñada para permitir que los usuarios se muevan por su espacio físico. Especificar XR_BOUNDARY_TYPE_NO_RECOMMENDATION no proporciona recomendaciones para el tipo de límite de seguridad, por lo que el sistema usa el tipo que ya está en uso.

<manifest ... >

   <application ... >
       <property
           android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED"
           android:value="XR_BOUNDARY_TYPE_LARGE" />
   </application>
</manifest>

Propiedades del contenedor espacial

Si tu app usa la extensión XR_EXT_spatial_container (presentada en el nivel de API espacial 4) para mostrar contenido en volúmenes 3D limitados o paneles 2D, además de vistas envolventes completas, puedes declarar las siguientes propiedades del manifiesto en el nivel <activity> o <application> para proporcionar sugerencias de inicio al entorno de ejecución:

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES: Especifica los modos de límites que usa la actividad, separados por |.

  Estos son los valores válidos:

  • "2d_panel"
  • "bounded"
  • "immersive"

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE: Especifica el modo de límites iniciales de la actividad cuando se inicia.

  Estos son los valores válidos:

  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED

Nota: Estas propiedades reemplazan la categoría de filtro de intents <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> cuando se usa XR_EXT_spatial_container.

<manifest ... >

   <application ... >
       <activity
           android:name="com.example.myapp.MainActivity" ... >
           <property
               android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
               android:value="bounded|immersive" />
           <property
               android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
               android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED" />
       </activity>
   </application>
</manifest>

<uses-native-library> OpenXR

Las aplicaciones de OpenXR deben declarar el uso de la biblioteca nativa de OpenXR para cargar correctamente su entorno de ejecución. Sin esta declaración, el entorno de ejecución no se carga.

<manifest ... >

    <application ... >

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

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

Funciones de PackageManager para apps de RE

Cuando distribuyes apps a través de Google Play Store, puedes especificar las funciones de hardware o software necesarias en el manifiesto de la app. El elemento uses-feature permite que Play Store filtre de forma adecuada las apps que se muestran a los usuarios.

Las siguientes funciones son específicas de las apps diferenciadas para XR.

android.software.xr.api.openxr

Las apps que se orientan a la plataforma de Android XR y se compilan con OpenXR o Unity deben incluir esta función en el manifiesto de la app con el atributo android:required establecido en true.

Las apps que usan el paquete de extensiones de Android XR para Unity versión 1.0.0 o posterior, o el paquete de Android XR para Unity OpenXR versión 0.5.0-exp.1 o posterior no tienen que agregar este elemento de forma manual al manifiesto de la app. Estos dos paquetes insertarán este elemento en el manifiesto de la app por ti.

Los dispositivos pueden especificar una versión para esta función, que indica la versión más alta de OpenXR que admite el dispositivo. Los 16 bits superiores representan el número mayor, y los 16 bits inferiores, el número menor. Por ejemplo, para especificar la versión 1.1 de OpenXR, el valor se establecería en "0x00010001".

Las apps pueden usar la versión de la función para indicar una versión mínima de OpenXR que requieren. Por ejemplo, si tu app requiere compatibilidad con OpenXR 1.1, declara la siguiente función:

<uses-feature android:name="android.software.xr.api.openxr"
    android:version="0x00010001"
    android:required="true" />

android.software.xr.api.spatial

Las apps de OpenXR que requieren extensiones introducidas en una versión de la API espacial de Android XR específica pueden declarar la función android.software.xr.api.spatial con android:version establecido en el nivel de API espacial mínimo requerido (como "1", "2", "3" o "4"). Consulta Cómo compilar con extensiones de OpenXR compatibles para verificar la versión de la API espacial requerida para cada extensión.

<!-- Indicates that the app requires Android XR Spatial API Level 4 or higher. -->
<uses-feature android:name="android.software.xr.api.spatial"
    android:version="4"
    android:required="true" />

android.hardware.xr.input.controller

Esta función indica que la app requiere la entrada de un controlador de movimiento de alta precisión de 6DoF (grados de libertad) para funcionar correctamente. Si tu app admite controles y no puede funcionar sin ellos, establece el valor en true. Si tu app admite controles, pero puede funcionar sin ellos, configúrala como false.

Nota: Los controles de movimiento de 6DoF son un par de controles de hardware, uno para cada mano. Cada control se rastrea de forma independiente en el espacio a través de seis grados de libertad, tanto en movimientos lineales como de rotación. Por lo general, estos controles tienen varios botones de hardware, incluido un gatillo, y respuesta táctil.

<!-- Sets android:required to true, indicating that your app can't function on devices without controllers. -->
<uses-feature android:name="android.hardware.xr.input.controller" android:required="true" />

android.hardware.xr.input.hand_tracking

Esta marca indica que la app requiere un monitoreo de manos de alta fidelidad para funcionar correctamente, lo que incluye la posición, la orientación y la velocidad de las articulaciones de la mano del usuario. Si tu app admite el monitoreo de manos y no puede funcionar sin él, establece el valor en true. Si tu app admite el monitoreo de manos, pero puede funcionar sin él, configúralo como false.

Nota: Esta marca no es necesaria para detectar gestos básicos, como pellizcar, tocar, apuntar y agarrar.

<!-- Sets android:required to true, indicating that your app can't function on devices without hand tracking. -->
<uses-feature android:name="android.hardware.xr.input.hand_tracking" android:required="true" />

android.hardware.xr.input.eye_tracking

Este indicador señala que la app requiere un seguimiento de ojos de alta fidelidad para que la entrada funcione correctamente. Si tu app admite el seguimiento de ojos para la entrada y no puede funcionar sin él, establece el valor en true. Si tu app admite el seguimiento de ojos para la entrada, pero puede funcionar sin él, establécelo en false.

<!-- Sets android:required to true, indicating that your app can't function on devices without eye tracking. -->
<uses-feature android:name="android.hardware.xr.input.eye_tracking" android:required="true" />

android.hardware.xr.input.face_tracking

Esta marca indica que la app requiere hardware de seguimiento facial para funcionar correctamente. Si tu app admite el seguimiento facial y no puede funcionar sin él, establece el valor en true. Si tu app admite el seguimiento facial, pero puede funcionar sin él, configúralo como false.

<!-- Sets android:required to true, indicating that your app can't function on devices without face tracking. -->
<uses-feature android:name="android.hardware.xr.input.face_tracking" android:required="true" />

android.hardware.location.gps

Esta marca indica que la app usa la ubicación precisa del GPS en el dispositivo, como cuando se usan extensiones geoespaciales de OpenXR (XR_ANDROID_geospatial y XR_ANDROID_geospatial_anchor). Establece android:required en true si tu app no puede funcionar sin hardware de GPS o false si puede funcionar sin él.

<uses-feature android:name="android.hardware.location.gps" android:required="false" />

Nota: El seguimiento de manos, ojos, rostro y cuerpo, la comprensión de escenas y la ubicación son funciones sensibles a la privacidad y requieren que las apps soliciten permisos de tiempo de ejecución. Consulta Información sobre los permisos para XR para obtener más información sobre cómo declarar y solicitar permisos.

Información sobre los permisos para OpenXR

Muchas extensiones de OpenXR acceden a datos de sensores y capacidades sensibles para la privacidad. Para usar estas extensiones, tu app debe declarar los elementos <uses-permission> requeridos en su archivo AndroidManifest.xml y solicitar permisos peligrosos en el entorno de ejecución antes de llamar a las funciones de OpenXR correspondientes.

<manifest ... >
    <!-- Example dangerous permissions required by specific OpenXR extensions -->
    <uses-permission android:name="android.permission.SCENE_UNDERSTANDING_COARSE" />
    <uses-permission android:name="android.permission.HAND_TRACKING" />
    ...
</manifest>

En la siguiente tabla, se resumen los permisos peligrosos de Android que requieren las extensiones de OpenXR compatibles en Android XR. Para obtener todos los detalles sobre los permisos de XR en todos los SDKs, consulta Información sobre los permisos para XR.

Permiso	Funciones	Extensiones de OpenXR
android.permission.EYE_TRACKING_COARSE	Pose, estado y orientación de los ojos de baja precisión (como para los avatares)	XR_ANDROID_eye_tracking (xrGetCoarseTrackingEyesInfoANDROID)
android.permission.EYE_TRACKING_FINE	Mirada de alta precisión para la selección, la entrada, las interacciones y la renderización foveada con seguimiento de ojos.	XR_ANDROID_eye_tracking (xrGetFineTrackingEyesInfoANDROID) XR_EXT_eye_gaze_interaction XR_META_foveation_eye_tracked XR_VARJO_foveated_rendering
android.permission.FACE_TRACKING	Seguimiento de las formas de mezcla faciales y renderización de las expresiones faciales	XR_ANDROID_face_tracking XR_ANDROID_face_tracking_data_source
android.permission.RECORD_AUDIO	Entrada de audio para fuentes de datos de seguimiento facial basadas en audio.	XR_ANDROID_face_tracking_data_source
android.permission.HAND_TRACKING	Seguimiento de las poses de las articulaciones de las manos, las velocidades, el estado de apuntado y la representación de la malla de la mano.	XR_ANDROID_hand_mesh XR_EXT_hand_tracking XR_FB_hand_tracking_aim XR_FB_hand_tracking_mesh
android.permission.BODY_TRACKING	Seguimiento de las poses de las articulaciones del cuerpo y las proporciones del esqueleto	XR_ANDROID_body_tracking
android.permission.SCENE_UNDERSTANDING_COARSE	Seguimiento de planos, seguimiento de objetos, seguimiento de imágenes, marcadores y códigos QR, anclajes, persistencia, proyección de rayos contra elementos rastreables, estimación de luz y mallas de transferencia.	XR_ANDROID_anchor_sharing_export XR_ANDROID_composition_layer_passthrough_mesh XR_ANDROID_device_anchor_persistence XR_ANDROID_light_estimation XR_ANDROID_raycast XR_ANDROID_spatial_anchor_space XR_ANDROID_spatial_component_subsumed_by XR_ANDROID_spatial_discovery_bounds XR_ANDROID_spatial_entity_bound_anchor XR_ANDROID_spatial_object_tracking XR_ANDROID_trackables XR_ANDROID_trackables_image XR_ANDROID_trackables_marker XR_ANDROID_trackables_object XR_ANDROID_trackables_qr_code XR_EXT_spatial_anchor XR_EXT_spatial_image_tracking XR_EXT_spatial_marker_tracking XR_EXT_spatial_mesh_tracking XR_EXT_spatial_object_tracking XR_EXT_spatial_persistence XR_EXT_spatial_persistence_operations XR_EXT_spatial_plane_tracking
android.permission.SCENE_UNDERSTANDING_FINE	Texturas de profundidad, creación de mallas de escenas, estimación de luz de mapa de cubo, trazado de rayos de profundidad y anotaciones espaciales.	XR_ANDROID_depth_texture XR_ANDROID_light_estimation_cubemap XR_ANDROID_scene_meshing XR_ANDROID_spatial_annotation_tracking XR_ANDROID_spatial_discovery_raycast
android.permission.ACCESS_FINE_LOCATION	Ubicación y orientación precisas en relación con la Tierra para el seguimiento y las anclas geoespaciales.	XR_ANDROID_geospatial XR_ANDROID_geospatial_anchor

Próximos pasos

Ahora que terminaste de configurar el manifiesto de tu app y de revisar la información importante, explora las formas en que puedes compilar con OpenXR:

• Compila con extensiones de OpenXR compatibles
• Compila con motores compatibles