開始使用 Android XR 的 OpenXR

適用的 XR 裝置

本指南可協助您為這類 XR 裝置打造體驗。

瞭解 XR 裝置類型 →

XR 頭戴式裝置

有線 XR 眼鏡

瞭解 XR 裝置類型 →

開始使用支援的 OpenXR 擴充功能或引擎建構應用程式前，請詳閱下列各節的資訊清單設定和權限規定，確認應用程式已針對 XR 開發作業完成設定。

設定應用程式的資訊清單檔案

與其他 Android 應用程式專案一樣，Android XR 應用程式必須有 AndroidManifest.xml 檔案，並包含特定資訊清單設定。資訊清單檔案會將應用程式的基本資訊，提供給 Android 建構工具、Android 作業系統和 Google Play。詳情請參閱應用程式資訊清單總覽指南。

注意： 雖然使用 Unity、Unreal Engine 或 Godot 建構的 Android XR 應用程式是以 OpenXR 為基礎，但如果您使用這些引擎的官方 Android XR 外掛程式，就不需要手動新增大部分資訊清單元素或屬性。引擎外掛程式和匯出預設設定會根據專案和建構設定，為應用程式設定資訊清單。

如果是 XR 差異化應用程式，資訊清單檔案必須包含下列元素和屬性：

PROPERTY_XR_ACTIVITY_START_MODE 屬性

android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" 屬性可讓系統知道，活動啟動時應以特定模式啟動。

這項屬性具有下列值：

• XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED (僅限 OpenXR)

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

使用 OpenXR 建構的應用程式會在全螢幕模式下啟動，且必須使用 XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED 啟動模式。非代管全螢幕會向 Android XR 發出信號，表示應用程式使用 OpenXR。

注意： 如果您使用 Unity 的 Android XR 套件，應用程式也會在全螢幕模式下啟動。不過，您不必手動將這項權限新增至資訊清單。Unity 套件會根據專案和建構設定，為應用程式建立資訊清單。

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

android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED" 屬性表示應用程式應以特定類型的邊界啟動。如果應用程式設計目的是讓使用者在實體空間中移動，則必須指定 XR_BOUNDARY_TYPE_LARGE。指定 XR_BOUNDARY_TYPE_NO_RECOMMENDATION 時，系統不會提供安全邊界類型的建議，而是使用目前使用的類型。

<manifest ... >

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

空間容器屬性

如果應用程式使用 XR_EXT_spatial_container 擴充功能 (Spatial API 級別 4 推出)，除了全沉浸式檢視畫面外，還會在有邊界的 3D 體積或 2D 面板中顯示內容，您可以在 <activity> 或 <application> 層級宣告下列資訊清單屬性，向執行階段提供啟動提示：

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES：指定活動使用的邊界模式，以 | 分隔。

  有效值如下：

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

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE：指定活動啟動時的初始邊界模式。

  有效值如下：

  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED

注意： 使用 XR_EXT_spatial_container 時，這些屬性會取代 <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> 意圖篩選器類別。

<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 應用程式必須宣告使用原生 OpenXR 程式庫，才能成功載入執行階段。如果沒有這項宣告，執行階段就無法載入。

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

XR 應用程式的 PackageManager 功能

透過 Google Play 商店發行應用程式時，您可以在應用程式資訊清單中指定必要的硬體或軟體功能。uses-feature 元素可讓 Play 商店適當篩選向使用者顯示的應用程式。

下列功能僅適用於 XR 差異化應用程式。

android.software.xr.api.openxr

如果應用程式指定 Android XR 平台，且是以 OpenXR 或 Unity 建構，則必須在應用程式資訊清單中加入這項功能，並將 android:required 屬性設為 true。

如果應用程式使用 Android XR Extensions Package for Unity 1.0.0 以上版本，或 Unity OpenXR: Android XR Package 0.5.0-exp.1 以上版本，就不必手動將這個元素新增至應用程式資訊清單。這兩個套件會為您將這個元素插入應用程式資訊清單。

裝置可以指定這項功能的版本，代表裝置支援的 OpenXR 最高版本。較高的 16 位元代表主要編號，較低的 16 位元代表次要編號。舉例來說，如要指定 OpenXR 1.1 版，請將值設為 "0x00010001"。

應用程式可以使用功能版本，指出應用程式所需的 OpenXR 最低版本。舉例來說，如果應用程式需要 OpenXR 1.1 版支援，請宣告下列功能：

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

android.software.xr.api.spatial

如果 OpenXR 應用程式需要特定 Android XR Spatial API 版本中導入的擴充功能，可以宣告 android.software.xr.api.spatial 功能，並將 android:version 設為所需的最低 Spatial API 級別 (例如 "1"、"2"、"3" 或 "4")。請參閱「使用支援的 OpenXR 擴充功能建構」，查看各項擴充功能所需的 Spatial API 版本。

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

這項功能表示應用程式需要高精確度的 6DoF (自由度) 動作控制器輸入，才能正常運作。如果應用程式支援控制器，且沒有控制器就無法運作，請將值設為 true。如果應用程式支援控制器，但沒有控制器也能運作，請設為 false。

注意： 6DoF 動作控制器是一對硬體控制器，左右手各一個。每個控制器都會透過六個自由度 (包括線性和旋轉動作) 在空間中獨立追蹤。這類控制器通常有多個硬體按鈕，包括觸發器和觸覺回饋。

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

這個旗標表示應用程式需要高擬真手勢追蹤功能，才能正常運作，包括使用者手部關節的位置、方向和速度。如果應用程式支援手勢追蹤，且必須有這項功能才能運作，請將值設為 true。如果應用程式支援手勢追蹤，但沒有這項功能也能運作，請設為 false。

注意： 偵測捏、戳、瞄準和抓握等基本手勢時，不需要這個旗標。

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

這個旗標表示應用程式需要高擬真度眼動追蹤，才能正確輸入。如果應用程式支援眼動追蹤輸入功能，且必須啟用這項功能才能運作，請將值設為 true。如果應用程式支援眼動追蹤輸入，但沒有這項功能也能運作，請設為 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

這個旗標表示應用程式需要臉部追蹤硬體才能正常運作。如果應用程式支援臉部追蹤功能，且沒有這項功能就無法運作，請將值設為 true。如果應用程式支援臉部追蹤，但沒有這項功能也能運作，請將其設為 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

這個旗標表示應用程式會使用裝置上的精確 GPS 位置，例如使用地理空間 OpenXR 擴充功能 (XR_ANDROID_geospatial 和 XR_ANDROID_geospatial_anchor)。如果應用程式必須有 GPS 硬體才能運作，請將 android:required 設為 true，否則請設為 false。

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

注意： 手勢追蹤、眼動追蹤、臉部追蹤、身體追蹤、場景理解和位置資訊，都是涉及隱私權的功能，應用程式必須要求執行階段權限才能使用。如要進一步瞭解如何宣告及要求權限，請參閱「瞭解 XR 權限」。

瞭解 OpenXR 權限

許多 OpenXR 擴充功能會存取隱私權敏感的感應器資料和功能。如要使用這些擴充功能，應用程式必須在 AndroidManifest.xml 檔案中宣告必要的 <uses-permission> 元素，並在執行階段要求危險權限，才能呼叫對應的 OpenXR 函式。

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

下表列出 Android XR 支援的 OpenXR 擴充功能所需的危險 Android 權限。如要進一步瞭解所有 SDK 的 XR 權限，請參閱「瞭解 XR 權限」。

權限	功能	OpenXR 擴充功能
android.permission.EYE_TRACKING_COARSE	低精確度的眼睛姿勢、狀態和方向 (例如用於顯示虛擬化身)。	XR_ANDROID_eye_tracking (xrGetCoarseTrackingEyesInfoANDROID)
android.permission.EYE_TRACKING_FINE	高精確度的視線追蹤功能，可用於選取、輸入、互動，以及眼動追蹤凹形渲染。	XR_ANDROID_eye_tracking (xrGetFineTrackingEyesInfoANDROID) XR_EXT_eye_gaze_interaction XR_META_foveation_eye_tracked XR_VARJO_foveated_rendering
android.permission.FACE_TRACKING	追蹤臉部混合形狀並算繪臉部表情。	XR_ANDROID_face_tracking XR_ANDROID_face_tracking_data_source
android.permission.RECORD_AUDIO	音訊輸入，用於音訊驅動的臉部追蹤資料來源。	XR_ANDROID_face_tracking_data_source
android.permission.HAND_TRACKING	追蹤手部關節姿勢、速度、瞄準狀態和手部網格表示法。	XR_ANDROID_hand_mesh XR_EXT_hand_tracking XR_FB_hand_tracking_aim XR_FB_hand_tracking_mesh
android.permission.BODY_TRACKING	追蹤身體關節姿勢和骨骼比例。	XR_ANDROID_body_tracking
android.permission.SCENE_UNDERSTANDING_COARSE	平面追蹤、物件追蹤、圖片/標記/QR code 追蹤、錨點、持續性、可追蹤物件的光線投射、光線估算和透視網格。	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	深度紋理、場景網格、立方體對應光源估算、深度光線投射和空間註解。	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	提供精確的地球相對位置和方向，用於地理空間追蹤和錨點。	XR_ANDROID_geospatial XR_ANDROID_geospatial_anchor

後續步驟

完成應用程式資訊清單設定並詳閱重要資訊後，請探索如何使用 OpenXR 建構：

• 使用支援的 OpenXR 擴充功能建構
• 使用支援的引擎建構