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

面向 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 为 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 浏览器（如 Android XR 上的 Chrome）中的 VR 和 AR 设备的访问。

如果您想为网络构建 XR 体验，或者想为 Web 应用添加 XR 功能，请选择此选项。现有的 WebXR 体验也将适用于 Android XR。

了解有关使用 WebXR 构建 Web 应用的更多信息.

为 XR 进行设计

XR 将设计表面扩展到传统平面屏幕之外；您可以设计融合物理和虚拟现实的沉浸式体验。无论您是构建全新的体验，还是向现有应用添加沉浸式元素，Android XR 设计指南都能帮助您入门。

配置您应用的清单文件

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

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

PROPERTY_ACTIVITY_XR_START_MODE 属性

android:name="android.window.PROPERTY_ACTIVITY_XR_START_MODE" 属性让系统知道 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>

<uses-native-library> OpenXR

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

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


<manifest ... >

    <application ... >

    <uses-native-library android:name="libopenxr.google.so" android:required="true" />

       <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。如果您的应用专为支持 XR 的设备构建并在 Android XR 专用发布轨道上发布，则应将 android:required 属性设置为 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。

<uses-feature android:name="android.hardware.xr.input.controller" android:required="true" />

android.hardware.xr.input.hand_tracking

此标志表示应用需要高保真手部追踪才能正常运行，包括用户手部关节的位置、方向和速度。如果您的应用支持手部追踪且没有它无法运行，请将该值设置为 true。如果您的应用支持手部追踪但没有它也能运行，请将其设置为 false。

<uses-feature android:name="android.hardware.xr.input.hand_tracking" android:required="true" />

android.hardware.xr.input.eye_tracking

此标志表示应用需要高保真眼部追踪才能正常运行。如果您的应用支持眼部追踪输入且没有它无法运行，请将该值设置为 true。如果您的应用支持眼部追踪输入但没有它也能运行，请将其设置为 false。

<uses-feature android:name="android.hardware.xr.input.eye_tracking" android:required="true" />

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

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

不支持的功能

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

了解 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 应用包以及应用大小限制的信息。

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

面向 Android XR 构建应用的概览 通过收藏夹保持井井有条 根据您的偏好保存和分类内容。

选择您的开发工具和技术

Jetpack XR SDK

Unity

OpenXR

WebXR

为 XR 进行设计

配置您应用的清单文件

PROPERTY_ACTIVITY_XR_START_MODE 属性

XR_ACTIVITY_START_MODE_HOME_SPACE

XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

<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 构建应用的概览