Erste Schritte mit OpenXR für Android XR

XR‑Geräte, für die der Leitfaden gilt

Dieser Leitfaden hilft Ihnen dabei, Erlebnisse für die folgenden Arten von XR-Geräten zu entwickeln.

Informationen zu XR-Gerätetypen →

XR-Headsets

Kabelgebundene XR-Datenbrille

Informationen zu XR-Gerätetypen →

Bevor Sie mit der Entwicklung mit unterstützten OpenXR-Erweiterungen oder einer unterstützten Engine beginnen, sollten Sie sich die Manifestkonfiguration und die Berechtigungsanforderungen in den folgenden Abschnitten ansehen, um sicherzustellen, dass Ihre App für die XR-Entwicklung konfiguriert ist.

Manifestdatei der App konfigurieren

Wie bei anderen Android-App-Projekten muss Ihre Android XR-App eine AndroidManifest.xml-Datei mit bestimmten Manifesteinstellungen enthalten. Die Manifestdatei enthält wichtige Informationen zu deiner App für die Android-Build-Tools, das Android-Betriebssystem und Google Play. Weitere Informationen finden Sie im Leitfaden zum App-Manifest.

Hinweis: Apps, die mit Unity, Unreal Engine oder Godot für Android XR erstellt wurden, basieren auf OpenXR. Sie müssen die meisten dieser Manifestelemente oder ‑attribute jedoch nicht manuell hinzufügen, wenn Sie die offiziellen Android XR-Plug-ins für diese Engines verwenden. Die Engine-Plug-ins und Exportvoreinstellungen konfigurieren das Manifest für Ihre App basierend auf Ihren Projekt- und Build-Einstellungen.

Bei XR-differenzierten Apps muss die Manifestdatei die folgenden Elemente und Attribute enthalten:

PROPERTY_XR_ACTIVITY_START_MODE-Attribut

Mit dem Attribut android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" wird dem System mitgeteilt, dass eine Aktivität beim Start in einem bestimmten Modus gestartet werden soll.

Diese Property hat die folgenden Werte:

• XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED (nur OpenXR)

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

Mit OpenXR erstellte Apps werden im Full Space gestartet und müssen den Startmodus XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED verwenden. Unmanaged Full Space signalisiert Android XR, dass die App OpenXR verwendet.

Hinweis: Wenn Sie eines der Android XR-Pakete für Unity verwenden, wird Ihre App ebenfalls im Full Space gestartet. Sie müssen dies jedoch nicht manuell zu Ihrem Manifest hinzufügen. Die Unity-Pakete erstellen das Manifest für Ihre App basierend auf Ihren Projekt- und Build-Einstellungen.

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

PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED-Attribut

Das Attribut android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED" gibt an, dass die Anwendung mit einem bestimmten Begrenzungstyp gestartet werden soll. In Ihrer App muss XR_BOUNDARY_TYPE_LARGE angegeben werden, wenn sie so konzipiert ist, dass sich Nutzer in ihrer physischen Umgebung bewegen können. Wenn Sie XR_BOUNDARY_TYPE_NO_RECOMMENDATION angeben, werden keine Empfehlungen für den Typ der Sicherheitsgrenze bereitgestellt. Das System verwendet dann den bereits verwendeten Typ.

<manifest ... >

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

Eigenschaften des räumlichen Containers

Wenn deine App die Erweiterung XR_EXT_spatial_container (eingeführt in Spatial API Level 4) verwendet, um Inhalte in begrenzten 3D-Volumen oder 2D-Bereichen zusätzlich zu immersiven Ansichten darzustellen, kannst du die folgenden Manifesteigenschaften auf der Ebene <activity> oder <application> deklarieren, um der Laufzeit Hinweise zum Start zu geben:

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES: Gibt die von der Aktivität verwendeten Begrenzungsmodi an, getrennt durch |.

  Gültige Werte sind:

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

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE: Gibt den anfänglichen Begrenzungsmodus der Aktivität beim Start an.

  Gültige Werte sind:

  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED

Hinweis: Diese Attribute ersetzen die Intent-Filter-Kategorie <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />, wenn XR_EXT_spatial_container verwendet wird.

<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

OpenXR-Anwendungen müssen die Verwendung der nativen OpenXR-Bibliothek deklarieren, damit die Laufzeit erfolgreich geladen werden kann. Ohne diese Deklaration kann die Laufzeit nicht geladen werden.

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

PackageManager-Funktionen für XR-Apps

Wenn Sie Apps über den Google Play Store vertreiben, können Sie im App-Manifest erforderliche Hardware- oder Softwarefunktionen angeben. Mit dem Element uses-feature kann der Google Play Store die den Nutzern angezeigten Apps entsprechend filtern.

Die folgenden Funktionen sind spezifisch für XR-differenzierte Apps.

android.software.xr.api.openxr

Apps, die auf die Android XR-Plattform ausgerichtet sind und mit OpenXR oder Unity erstellt wurden, müssen diese Funktion im App-Manifest enthalten, wobei das Attribut android:required auf true gesetzt sein muss.

Apps, die das Android XR Extensions Package for Unity in Version 1.0.0 oder höher oder das Unity OpenXR: Android XR Package in Version 0.5.0-exp.1 oder höher verwenden, müssen dieses Element nicht manuell zum App-Manifest hinzufügen. Diese beiden Pakete fügen dieses Element für Sie in das App-Manifest ein.

Geräte können eine Version für diese Funktion angeben, die die höchste vom Gerät unterstützte OpenXR-Version angibt. Die höheren 16 Bit stellen die Hauptnummer und die niedrigeren 16 Bit die Nebennummer dar. Wenn Sie beispielsweise OpenXR-Version 1.1 angeben möchten, wird der Wert auf "0x00010001" festgelegt.

Apps können die Feature-Version verwenden, um eine Mindestversion von OpenXR anzugeben, die die App benötigt. Wenn deine App beispielsweise Unterstützung für OpenXR Version 1.1 erfordert, deklariere das folgende Feature:

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

android.software.xr.api.spatial

OpenXR-Apps, die Erweiterungen erfordern, die in einer bestimmten Spatial API-Version von Android XR eingeführt wurden, können das Feature android.software.xr.api.spatial deklarieren, wobei android:version auf das erforderliche Mindest-Spatial API-Level festgelegt ist (z. B. "1", "2", "3" oder "4"). Unter Mit unterstützten OpenXR-Erweiterungen entwickeln können Sie die für jede Erweiterung erforderliche Spatial API-Version prüfen.

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

Diese Funktion gibt an, dass die App Eingaben von einem hochpräzisen Motion-Controller mit 6 DoF (Degrees of Freedom, Freiheitsgrade) benötigt, um richtig zu funktionieren. Wenn deine App Controller unterstützt und ohne sie nicht funktioniert, setze den Wert auf true. Wenn deine App Controller unterstützt, aber auch ohne sie funktioniert, setze den Wert auf false.

Hinweis: 6DoF-Motion-Controller sind ein Paar Hardware-Controller, einer für jede Hand. Jeder Controller wird unabhängig im Raum mit sechs Freiheitsgraden verfolgt – sowohl lineare als auch Drehbewegungen. Diese Controller haben in der Regel mehrere Hardwaretasten, darunter einen Trigger, und bieten haptisches Feedback.

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

Dieses Flag gibt an, dass die App ein hochpräzises Handtracking benötigt, um richtig zu funktionieren, einschließlich Position, Ausrichtung und Geschwindigkeit der Gelenke in der Hand des Nutzers. Wenn Ihre App Handtracking unterstützt und ohne diese Funktion nicht funktioniert, legen Sie den Wert auf true fest. Wenn deine App Handtracking unterstützt, aber auch ohne funktioniert, lege false fest.

Hinweis: Dieses Flag ist nicht erforderlich, um einfache Gesten wie Zusammenführen, Tippen, Zielen und Greifen zu erkennen.

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

Dieses Flag gibt an, dass die App für die Eingabe ein hochpräzises Eye-Tracking benötigt, um richtig zu funktionieren. Wenn deine App Eye-Tracking für Eingaben unterstützt und ohne diese Funktion nicht funktioniert, setze den Wert auf true. Wenn Ihre App Eye-Tracking für die Eingabe unterstützt, aber auch ohne funktioniert, legen Sie den Wert auf false fest.

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

Dieses Flag gibt an, dass die App Hardware für die Mimik-Erkennung benötigt, um richtig zu funktionieren. Wenn Ihre App die Mimik-Erkennung unterstützt und ohne sie nicht funktioniert, setzen Sie den Wert auf true. Wenn Ihre App die Mimik-Erkennung unterstützt, aber auch ohne sie funktioniert, legen Sie false fest.

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

Dieses Flag gibt an, dass die App den genauen GPS-Standort auf dem Gerät verwendet, z. B. bei der Verwendung von OpenXR-Erweiterungen für Geodaten (XR_ANDROID_geospatial und XR_ANDROID_geospatial_anchor). Setzen Sie android:required auf true, wenn Ihre App ohne GPS-Hardware nicht funktioniert, oder auf false, wenn sie ohne GPS-Hardware funktioniert.

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

Hinweis: Handtracking, Augensteuerung, Mimik-Erkennung, Bodytracking, Szenenerkennung und Standort sind datenschutzrelevante Funktionen, für die Apps Laufzeitberechtigungen anfordern müssen. Weitere Informationen zum Deklarieren und Anfordern von Berechtigungen finden Sie unter Berechtigungen für XR.

Berechtigungen für OpenXR

Viele OpenXR-Erweiterungen greifen auf datenschutzrelevante Sensordaten und Funktionen zu. Wenn Sie diese Erweiterungen verwenden möchten, muss Ihre App sowohl die erforderlichen <uses-permission>-Elemente in der Datei AndroidManifest.xml deklarieren als auch gefährliche Berechtigungen zur Laufzeit anfordern, bevor die entsprechenden OpenXR-Funktionen aufgerufen werden.

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

In der folgenden Tabelle sind die gefährlichen Android-Berechtigungen zusammengefasst, die von unterstützten OpenXR-Erweiterungen unter Android XR benötigt werden. Ausführliche Informationen zu XR-Berechtigungen für alle SDKs finden Sie unter Berechtigungen für XR.

Berechtigung	Leistungsspektrum	OpenXR-Erweiterungen
android.permission.EYE_TRACKING_COARSE	Augenposition, ‑status und ‑ausrichtung mit geringer Genauigkeit (z. B. für Avatare).	XR_ANDROID_eye_tracking (xrGetCoarseTrackingEyesInfoANDROID)
android.permission.EYE_TRACKING_FINE	Hochpräzise Blickerfassung für Auswahl, Eingabe, Interaktionen und Eye-Tracking-basiertes Foveated Rendering.	XR_ANDROID_eye_tracking (xrGetFineTrackingEyesInfoANDROID) XR_EXT_eye_gaze_interaction XR_META_foveation_eye_tracked XR_VARJO_foveated_rendering
android.permission.FACE_TRACKING	Tracking von Gesichts-Blendshapes und Rendern von Gesichtsausdrücken.	XR_ANDROID_face_tracking XR_ANDROID_face_tracking_data_source
android.permission.RECORD_AUDIO	Audioeingabe für audiobasierte Datenquellen zur Mimik-Erkennung.	XR_ANDROID_face_tracking_data_source
android.permission.HAND_TRACKING	Tracking von Handgelenkpositionen, Geschwindigkeiten, Zielzustand und Hand-Mesh-Darstellung.	XR_ANDROID_hand_mesh XR_EXT_hand_tracking XR_FB_hand_tracking_aim XR_FB_hand_tracking_mesh
android.permission.BODY_TRACKING	Tracking von Körpergelenkpositionen und Skelettproportionen.	XR_ANDROID_body_tracking
android.permission.SCENE_UNDERSTANDING_COARSE	Ebenen-Tracking, Objekt-Tracking, Bild-/Markierungs-/QR-Code-Tracking, Anker, Persistenz, Raycasting für trackbare Objekte, Lichtschätzung und Passthrough-Meshes.	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	Tiefentexturen, Szenen-Meshing, Cubemap-Lichtschätzung, Tiefen-Raycasting und räumliche Annotationen.	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	Präzise, auf die Erde bezogene Position und Ausrichtung für raumbezogenes Tracking und raumbezogene Anker.	XR_ANDROID_geospatial XR_ANDROID_geospatial_anchor

Nächste Schritte

Nachdem du das Manifest deiner App konfiguriert und wichtige Informationen gelesen hast, kannst du dich mit den Möglichkeiten von OpenXR vertraut machen:

• Mit unterstützten OpenXR-Erweiterungen entwickeln
• Mit unterstützten Engines erstellen