Android XR SDK 现已推出开发者预览版。我们期望收到您的反馈！请访问我们的支持页面与我们联系。

此页面由 Cloud Translation API 翻译。

面向 Android XR 构建应用概览

Android XR 是 Android 平台和生态系统的扩展。Android XR SDK 旨在让您使用熟悉的 Android 框架和工具或使用 OpenXR 和 WebXR 等开放标准来构建 XR 应用。所有兼容的移动应用或大屏应用都将可在 Play 商店中安装到 XR 头戴设备上。查看兼容性注意事项，了解您的应用是否兼容。

本指南介绍了以下方面：

选择开发工具和技术
为 Android XR 设计应用
配置应用的清单文件
应用清单兼容性注意事项
了解 Android XR 的权限
验证 Android XR 应用质量
打包和分发 Android XR 应用

选择开发工具和技术

为 Android XR 构建应用时，您可以选择以下开发平台和技术：

Jetpack XR SDK

Jetpack XR SDK 包含 Android XR Jetpack 库，这些库旨在充分利用 XR 设备的独特功能。如果您想执行以下任一操作，请从该 SDK 开始：

优化或增强现有的 Android 手机或平板电脑应用
使用 Android Studio 和 Jetpack 构建新的 Android XR 应用

如果您已经能熟练地使用 Android Jetpack 进行开发，那么 Jetpack XR SDK 非常适合您。它旨在与这些框架和库无缝集成，让您能够利用现有知识来构建沉浸式 XR 体验。

详细了解如何使用 Jetpack XR SDK 进行开发。

Unity

Unity Engine 是一款实时 3D 开发引擎，可让艺术家、设计师和开发者协作打造沉浸式互动体验。借助 Unity 的 Android XR 支持，您可以高度掌控所开发的 3D 体验，同时受益于 Unity 成熟的 OpenXR 支持和开发者生态系统。

如果您已经使用 Unity 构建了 XR 体验，或者熟悉 Unity 开发，则可以从这个选项开始。

详细了解如何使用 Unity for Android XR 进行开发。

OpenXR

OpenXR 是一种免版税的开放标准，可用于构建高性能、多平台的 XR 体验。Android XR 支持 OpenXR 1.0 和 1.1，并且我们正在通过适用于 Android XR 的新扩展程序来扩展规范。由于 Android XR 基于开放标准构建，因此支持 OpenXR 和 Android 的开发工具应与 Android XR 兼容。

详细了解 Android XR 的 OpenXR 支持。

WebXR

借助 WebXR，您可以为 Web 构建沉浸式体验。它可在兼容的 Web 浏览器（例如 Android XR 上的 Chrome）中访问 VR 和 AR 设备。

如果您想为 Web 构建 XR 体验，或者想为 Web 应用添加 XR 功能，请从该选项开始。现有的 WebXR 体验也可在 Android XR 上运行。

详细了解如何使用 WebXR 构建 Web 应用。

针对 XR 设计应用

XR 将设计界面扩展到传统平板屏幕之外；您可以设计融合了现实和虚拟现实的沉浸式体验。无论您是打造全新体验，还是向现有应用添加沉浸式元素，Android 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_FULL_SPACE_UNMANAGED（仅限 OpenXR）

XR_ACTIVITY_START_MODE_HOME_SPACE

（仅限使用 Jetpack XR SDK 构建的应用）

使用此启动模式可在 Home Space 中启动应用。在 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

（仅限使用 Jetpack XR SDK 构建的应用）

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


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

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

（仅限使用 OpenXR 构建的应用）

使用 OpenXR 构建的应用会在 Full Space 中启动，并且必须使用 XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED 启动模式。非受管 Full Space 向 Android XR 发出信号，表明应用使用 OpenXR。


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

<uses-native-library> OpenXR

（仅限使用 OpenXR 构建的应用）

OpenXR 应用必须声明使用原生 OpenXR 库，才能成功加载其运行时。如果没有此声明，运行时将无法加载。

<manifest ... >

    <application ... >

    <uses-native-library andro id: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.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.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.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" />

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

如 XR 应用的 PackageManager 功能部分中所述，应用通过在应用清单的 <uses-feature> 元素中声明功能来表明其使用该功能。某些功能（例如电话或 GPS）可能无法在所有设备上使用。

了解 XR 的权限

与移动设备和其他设备规格上的应用一样，XR 应用提供的某些功能可能需要您的应用在 AndroidManifest 文件中声明权限。对于危险权限，您的应用可能需要请求运行时权限。如需了解更深入的信息，请参阅 Android 中的权限和权限最佳实践。

XR 应用可能会使用以下权限。此部分中的所有权限都被视为危险权限，因此您必须在应用清单中声明这些权限并在运行时请求这些权限。

android.permission.EYE_TRACKING_COARSE

表示用户的眼部姿势、状态和方向，例如用于头像。当需要低精度眼动追踪数据时，请使用此权限。

Jetpack XR SDK

不适用

OpenXR 扩展

Unity 功能

Android XR：AR Face

android.permission.EYE_TRACKING_FINE

通过眼球注视进行选择、输入和互动。

Jetpack XR SDK

不适用

OpenXR 扩展

Unity 功能

眼动交互

android.permission.FACE_TRACKING

跟踪和渲染面部表情。

Jetpack XR SDK

不适用

OpenXR 扩展

XR_ANDROID_face_tracking

Unity 功能

XRFaceTrackingFeature

android.permission.HAND_TRACKING

跟踪手部关节姿势以及角速度和线速度；使用用户手部的网格表示形式。

Jetpack XR SDK

手部状态和关节姿势

OpenXR 扩展

Unity 功能

android.permission.SCENE_UNDERSTANDING_COARSE

光照估计；将透视效果投影到网格表面上；针对环境中的可跟踪对象执行光线投射；平面跟踪；对象跟踪；持久锚点。

Jetpack XR SDK

OpenXR 扩展

Unity 功能

android.permission.SCENE_UNDERSTANDING_FINE

深度纹理。

Jetpack XR SDK

不适用

OpenXR 扩展

XR_ANDROID_depth_texture

Unity 功能

XRDepthTextureFeature

验证 Android XR 应用质量

如需验证您的应用是否能提供出色的用户体验，请查看我们的 Android XR 应用质量准则。

打包和分发 Android XR 应用

Android XR 通过 Google Play 为 XR 头戴式设备带来各种各样的应用和体验。在打包和分发 Android XR 应用指南中，您将找到有关以下方面的信息：Play 商店和 Play 管理中心入门、发布轨道、准备 Android App Bundle 以及应用大小限制。

OpenXR™ 和 OpenXR 徽标是 The Khronos Group Inc. 拥有的商标，已在中国、欧盟、日本和英国注册为商标。

面向 Android XR 构建应用概览 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

选择开发工具和技术

Jetpack XR SDK

Unity

OpenXR

WebXR

针对 XR 设计应用

配置应用的清单文件

PROPERTY_XR_ACTIVITY_START_MODE 属性

XR_ACTIVITY_START_MODE_HOME_SPACE

XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED 属性

<uses-native-library> OpenXR

XR 应用的 PackageManager 功能

android.software.xr.api.spatial

android.software.xr.api.openxr

android.hardware.xr.input.controller

android.hardware.xr.input.hand_tracking

android.hardware.xr.input.eye_tracking

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

不支持的功能

相机硬件

连接

设备配置

设备规格配置

输入

位置

近距离无线通信

安全配置和硬件

传感器

软件配置

电话

虚拟现实（旧版）

微件

了解 XR 的权限

android.permission.EYE_TRACKING_COARSE

Jetpack XR SDK

OpenXR 扩展

Unity 功能

android.permission.EYE_TRACKING_FINE

Jetpack XR SDK

OpenXR 扩展

Unity 功能

android.permission.FACE_TRACKING

Jetpack XR SDK

OpenXR 扩展

Unity 功能

android.permission.HAND_TRACKING

Jetpack XR SDK

OpenXR 扩展

Unity 功能

android.permission.SCENE_UNDERSTANDING_COARSE

Jetpack XR SDK

OpenXR 扩展

Unity 功能

android.permission.SCENE_UNDERSTANDING_FINE

Jetpack XR SDK

OpenXR 扩展

Unity 功能

验证 Android XR 应用质量

打包和分发 Android XR 应用

面向 Android XR 构建应用概览