Inizia a utilizzare OpenXR per Android XR

Dispositivi XR applicabili

Queste indicazioni ti aiutano a creare esperienze per questi tipi di dispositivi XR.

Scopri di più sui tipi di dispositivi XR →

Visori XR

Occhiali XR con cavo

Scopri di più sui tipi di dispositivi XR →

Prima di iniziare a creare con le estensioni OpenXR supportate o con un motore supportato, esamina i requisiti di configurazione e autorizzazione del manifest nelle sezioni seguenti per assicurarti che la tua app sia configurata per lo sviluppo XR.

Configura il file manifest dell'app

Come per altri progetti di app per Android, la tua app per Android XR deve avere un file AndroidManifest.xml con impostazioni manifest specifiche. Il file manifest descrive le informazioni essenziali sulla tua app per gli strumenti di build di Android, il sistema operativo Android e Google Play. Per saperne di più, consulta la guida Panoramica del file manifest dell'app.

Nota: anche se le app create con Unity, Unreal Engine o Godot per Android XR si basano su OpenXR, non è necessario aggiungere manualmente la maggior parte di questi elementi o attributi del manifest se utilizzi i plug-in Android XR ufficiali per questi motori. I plug-in del motore e i preset di esportazione configurano il manifest per la tua app in base alle impostazioni del progetto e della build.

Per le app XR differenziate, il file manifest deve contenere i seguenti elementi e attributi:

Proprietà PROPERTY_XR_ACTIVITY_START_MODE

La proprietà android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" consente al sistema di sapere che un'attività deve essere avviata in una modalità specifica quando viene avviata.

Questa proprietà ha i seguenti valori:

• XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED (solo OpenXR)

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

Le app create con OpenXR vengono avviate in spazio intero e devono utilizzare la modalità di avvio XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED. Lo spazio intero non gestito indica ad Android XR che l'app utilizza OpenXR.

Nota: se utilizzi uno dei pacchetti Android XR per Unity, l'app verrà avviata anche in spazio intero. Tuttavia, non è necessario aggiungerlo manualmente al manifest. I pacchetti Unity creano il manifest per la tua app in base alle impostazioni del progetto e della build.

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

Proprietà PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED

La proprietà android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED" indica che l'applicazione deve essere avviata con un tipo specifico di confine. La tua app deve specificare XR_BOUNDARY_TYPE_LARGE se è progettata per consentire agli utenti di muoversi nello spazio fisico. Se specifichi XR_BOUNDARY_TYPE_NO_RECOMMENDATION, non vengono forniti suggerimenti per il tipo di confine di sicurezza, pertanto il sistema utilizza il tipo già in uso.

<manifest ... >

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

Proprietà del container spaziale

Se la tua app utilizza l'estensione XR_EXT_spatial_container (introdotta nel livello API Spatial 4) per presentare contenuti in volumi 3D limitati o pannelli 2D oltre alle visualizzazioni immersive complete, puoi dichiarare le seguenti proprietà del manifest a livello di <activity> o <application> per fornire suggerimenti di avvio al runtime:

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES: specifica le modalità dei limiti utilizzate dall'attività, separate da |.

  I valori validi sono:

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

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE: specifica la modalità dei limiti iniziali dell'attività al momento del lancio.

  I valori validi sono:

  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED

Nota: queste proprietà sostituiscono la categoria del filtro per intent <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> quando utilizzi 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

Le applicazioni OpenXR devono dichiarare l'utilizzo della libreria OpenXR nativa per caricare correttamente il relativo runtime. Senza questa dichiarazione, il runtime non viene caricato.

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

Funzionalità di PackageManager per le app XR

Quando distribuisci app tramite il Google Play Store, puoi specificare le funzionalità hardware o software richieste nel file manifest dell'app. L'elemento uses-feature consente al Play Store di filtrare in modo appropriato le app mostrate agli utenti.

Le seguenti funzionalità sono specifiche per le app differenziate per XR.

android.software.xr.api.openxr

Le app che hanno come target la piattaforma Android XR e sono create con OpenXR o Unity devono includere questa funzionalità nel manifest dell'app con l'attributo android:required impostato su true.

Le app che utilizzano il pacchetto di estensioni Android XR per Unity versione 1.0.0 o successive o il pacchetto Unity OpenXR: Android XR versione 0.5.0-exp.1 o successive non devono aggiungere manualmente questo elemento al manifest dell'app. Questi due pacchetti inseriranno questo elemento nel manifest dell'app per te.

I dispositivi possono specificare una versione per questa funzionalità, che indica la versione più recente di OpenXR supportata dal dispositivo. I 16 bit superiori rappresentano il numero principale, mentre i 16 bit inferiori rappresentano il numero secondario. Ad esempio, per specificare la versione 1.1 di OpenXR, il valore deve essere impostato su "0x00010001".

Le app possono utilizzare la versione della funzionalità per indicare una versione minima di OpenXR richiesta dall'app. Ad esempio, se la tua app richiede il supporto di OpenXR versione 1.1, dichiara la seguente funzionalità:

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

android.software.xr.api.spatial

Le app OpenXR che richiedono estensioni introdotte in una specifica versione dell'API Spatial di Android XR possono dichiarare la funzionalità android.software.xr.api.spatial con android:version impostato sul livello API minimo richiesto dell'API Spatial (ad esempio "1", "2", "3" o "4"). Consulta Crea con le estensioni OpenXR supportate per verificare la versione dell'API Spatial richiesta per ogni estensione.

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

Questa funzionalità indica che l'app richiede l'input di un controller di movimento 6DoF (gradi di libertà) ad alta precisione per funzionare correttamente. Se la tua app supporta i controller e non può funzionare senza, imposta il valore su true. Se la tua app supporta i controller, ma può funzionare anche senza, impostala su false.

Nota: i controller di movimento 6DoF sono una coppia di controller hardware, uno per ogni mano. Ogni controller viene monitorato in modo indipendente nello spazio attraverso sei gradi di libertà, ovvero movimenti sia lineari che rotazionali. Questi controller in genere hanno diversi tasti hardware, tra cui un grilletto e un feedback aptico.

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

Questo flag indica che l'app richiede il tracciamento delle mani ad alta fedeltà per funzionare correttamente, inclusi posizione, orientamento e velocità delle articolazioni della mano dell'utente. Se la tua app supporta il tracciamento delle mani e non può funzionare senza, imposta il valore su true. Se la tua app supporta il tracciamento delle mani, ma può funzionare senza, impostala su false.

Nota: questo flag non è obbligatorio per rilevare gesti di base come pizzicare, toccare, mirare e afferrare.

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

Questo flag indica che l'app richiede il tracciamento oculare ad alta fedeltà per l'input per funzionare correttamente. Se la tua app supporta il tracciamento oculare per l'input e non può funzionare senza, imposta il valore su true. Se la tua app supporta il tracciamento oculare per l'input, ma può funzionare anche senza, impostalo su 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

Questo flag indica che l'app richiede l'hardware di tracciamento facciale per funzionare correttamente. Se la tua app supporta il tracciamento facciale e non può funzionare senza, imposta il valore su true. Se la tua app supporta il tracciamento facciale, ma può funzionare senza, impostala su 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

Questo flag indica che l'app utilizza la posizione GPS precisa sul dispositivo, ad esempio quando utilizza le estensioni OpenXR geospaziali (XR_ANDROID_geospatial e XR_ANDROID_geospatial_anchor). Imposta android:required su true se la tua app non può funzionare senza l'hardware GPS o su false se può funzionare senza.

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

Nota: il tracciamento delle mani, il tracciamento oculare, il tracciamento facciale, il tracciamento del corpo, la comprensione della scena e la posizione sono funzionalità sensibili alla privacy e richiedono alle app di richiedere autorizzazioni di runtime. Consulta Informazioni sulle autorizzazioni per XR per ulteriori informazioni sulla dichiarazione e sulla richiesta di autorizzazioni.

Informazioni sulle autorizzazioni per OpenXR

Molte estensioni OpenXR accedono a dati e funzionalità dei sensori sensibili alla privacy. Per utilizzare queste estensioni, la tua app deve dichiarare gli elementi <uses-permission> richiesti nel file AndroidManifest.xml e richiedere autorizzazioni pericolose in fase di runtime prima di chiamare le funzioni OpenXR corrispondenti.

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

La tabella seguente riassume le autorizzazioni Android pericolose richieste dalle estensioni OpenXR supportate su Android XR. Per informazioni dettagliate sulle autorizzazioni XR per tutti gli SDK, consulta Informazioni sulle autorizzazioni per XR.

Autorizzazione	Funzionalità	Estensioni OpenXR
android.permission.EYE_TRACKING_COARSE	Posizione, stato e orientamento degli occhi a bassa precisione (ad esempio per gli avatar).	XR_ANDROID_eye_tracking (xrGetCoarseTrackingEyesInfoANDROID)
android.permission.EYE_TRACKING_FINE	Sguardo ad alta precisione per selezione, input, interazioni e rendering foveated con tracciamento oculare.	XR_ANDROID_eye_tracking (xrGetFineTrackingEyesInfoANDROID) XR_EXT_eye_gaze_interaction XR_META_foveation_eye_tracked XR_VARJO_foveated_rendering
android.permission.FACE_TRACKING	Tracciamento delle forme di fusione facciale e rendering delle espressioni facciali.	XR_ANDROID_face_tracking XR_ANDROID_face_tracking_data_source
android.permission.RECORD_AUDIO	Input audio per origini dati di tracciamento facciale basate sull'audio.	XR_ANDROID_face_tracking_data_source
android.permission.HAND_TRACKING	Tracciamento delle pose delle articolazioni delle mani, delle velocità, dello stato di puntamento e della rappresentazione della mesh delle mani.	XR_ANDROID_hand_mesh XR_EXT_hand_tracking XR_FB_hand_tracking_aim XR_FB_hand_tracking_mesh
android.permission.BODY_TRACKING	Monitoraggio delle posizioni delle articolazioni del corpo e delle proporzioni dello scheletro.	XR_ANDROID_body_tracking
android.permission.SCENE_UNDERSTANDING_COARSE	Tracciamento di piani, oggetti, immagini/marker/codici QR, ancoraggi, persistenza, raycasting su elementi tracciabili, stima della luce e mesh passthrough.	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	Texture di profondità, meshing della scena, stima della luce della mappa cubica, raycasting di profondità e annotazioni spaziali.	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	Posizione e orientamento precisi rispetto alla Terra per il monitoraggio e le ancora geospaziali.	XR_ANDROID_geospatial XR_ANDROID_geospatial_anchor

Passaggi successivi

Ora che hai terminato di configurare il manifest dell'app e di esaminare le informazioni importanti, scopri i modi in cui puoi creare con OpenXR:

• Sviluppa con le estensioni OpenXR supportate
• Crea con i motori supportati