开始打造沉浸式体验

适用的 XR 设备
本指南可帮助您为以下类型的 XR 设备打造优质体验。
了解 XR 设备类型 →
扩展现实头戴设备
有线扩展现实眼镜
了解 XR 设备类型 →

安装并配置 Android Studio、创建项目并设置 Jetpack XR SDK 后，您就可以开始为 XR 头戴设备和有线 XR 眼镜等设备构建沉浸式体验了。

在开始探索各种构建方式之前，请先查看以下部分中的信息并完成其中的所有任务，确保您的应用已针对沉浸式 XR 开发进行了配置。

配置应用的清单文件

与其他 Android 应用项目一样，您的 Android XR 应用必须具有包含特定清单设置的 AndroidManifest.xml 文件。该清单文件会向 Android 构建工具、Android 操作系统和 Google Play 描述有关应用的基本信息。如需了解详情，请参阅应用清单概览指南。

对于 XR 差异化应用，清单文件必须包含以下元素和属性：

PROPERTY_XR_ACTIVITY_START_MODE 属性

android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" 属性可让系统知道，在启动 activity 时，应以特定模式启动该 activity。

此属性具有以下值：

  • XR_ACTIVITY_START_MODE_HOME_SPACE（仅限 Jetpack XR SDK）
  • XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED（仅限 Jetpack XR SDK）

XR_ACTIVITY_START_MODE_HOME_SPACE

使用此启动模式可在主共享空间中启动应用。在主共享空间中，多个应用可以并排运行，以便用户同时处理多项任务。任何移动或大屏 Android 应用都可以在 Home Space 中运行，使用 Jetpack XR SDK 构建的 XR 应用也可以。

<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

使用此启动模式可在全沉浸空间中启动应用。在全沉浸空间中，一次只运行一个应用，没有空间边界，所有其他应用都会隐藏。


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

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 应用的 PackageManager 功能

通过 Google Play 商店分发应用时，您可以在应用清单中指定所需的硬件或软件功能。借助 uses-feature 元素，Play 商店可以适当过滤向用户显示的应用。

以下功能仅适用于 XR 差异化应用。

android.software.xr.api.spatial

使用 Jetpack XR SDK 构建的应用必须在应用清单中包含此功能。您为 android:required 属性设置的值取决于应用的发布轨道。

如果您的应用将 XR 差异化功能或内容打包到现有移动 APK 中，并在移动发布轨道上发布，请将 android:required 属性设置为 false：

<!-- If you are publishing an existing mobile APK using the mobile release track, set android:required to false.-->
<uses-feature android:name="android.software.xr.api.spatial" android:required="false" />

如果您的应用专为支持 XR 的设备而构建，并发布到 Android XR 专用发布轨道，请将 android:required 属性设置为 true：

<!-- If you are publishing a separate APK for XR using the dedicated Android XR release track, set android:required to true.-->
<uses-feature android:name="android.software.xr.api.spatial" android:required="true" />

android.hardware.xr.input.controller

此功能表示应用需要来自高精度 6DoF（自由度）运动控制器的输入才能正常运行。如果您的应用支持控制器，并且没有控制器就无法运行，请将该值设置为 true。如果您的应用支持控制器，但也可以在没有控制器的情况下运行，请将其设置为 false。

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

移动应用和大屏应用的应用清单兼容性注意事项

如 PackageManager features for XR apps 部分所述，应用通过在应用清单中的 <uses-feature> 元素中声明其使用的功能来声明其使用的功能。某些功能（例如电话或 GPS）可能与部分设备不兼容。

如需获取为设备启用的功能列表，请运行 adb shell pm list features。

不支持的功能

Google Play 商店会使用以下 Android 功能声明过滤可在设备上安装的应用。

相机硬件

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

连接

android.hardware.ethernet

android.hardware.uwb

android.hardware.ipsec_tunnel_migration

设备配置

android.hardware.ram.low

设备规格配置

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

输入

android.hardware.consumerir

android.software.input_methods

位置

android.hardware.location.gps

近距离无线通信

android.hardware.nfc

android.hardware.nfc.ese

android.hardware.nfc.hce

android.hardware.nfc.hcef

android.hardware.nfc.uicc

android.hardware.nfc.beam

安全配置和硬件

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

传感器

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

软件配置

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

电话

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

虚拟现实（旧版）

android.hardware.vr.headtracking

android.hardware.vr.high_performance

android.software.vr.mode

微件

android.software.app_widgets

后续步骤

现在，您已完成应用清单的配置并查看了重要信息，接下来可以探索如何打造沉浸式体验：