为您的 Android 应用启用 Geospatial API (Kotlin/Java)

配置应用的设置，以便其可以使用 Geospatial API。

前提条件

在继续操作之前，请确保您了解基本 AR 概念以及如何配置 ARCore 会话。

示例应用和 Codelab

此视频将详细介绍使用 Geospatial API 构建一款应用的步骤，该应用可显示地理空间数据并将内容放置在真实地理位置。

您也可以按照地理空间 Codelab 文档中的步骤操作。如需运行在视频中创建的示例应用，请参阅 ARCore 地理空间快速入门。

如需详细了解 Geospatial API，请参阅 Geospatial API 简介。

如果您刚开始使用 ARCore 进行开发，请参阅使用入门，了解软件和硬件要求、前提条件以及特定于您所用平台的其他信息。

请确保您的开发环境满足 Quickstart 中所述的 ARCore SDK 要求。

启用 ARCore API

在应用中使用 Visual Positioning System (VPS) 之前，您必须先在新建或现有的 Google Cloud 项目中启用 ARCore API。此服务负责托管、存储和解析地理空间锚点。

首选无密钥授权，但也支持 API 密钥授权。

将所需的库添加到您的应用

授权应用调用 ARCore API 后，您必须添加库才能在应用中启用地理空间功能。

在应用的 build.gradle 文件中，设置 Google Play 服务以添加 Play 服务位置信息库。

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

在会话配置中启用地理空间功能

在创建会话之前，请将会话配置中的 GeospatialMode 更改为 ENABLED：

Java

Config config = session.getConfig();
config.setGeospatialMode(Config.GeospatialMode.ENABLED);
session.configure(config);

Kotlin

// Enable the Geospatial API.
session.configure(session.config.apply { geospatialMode = Config.GeospatialMode.ENABLED })

当地理空间模式设置为 ENABLED 时，应用可以从 Visual Positioning System (VPS) 获取地理信息。

提示用户允许使用设备数据

使用 ARCore Geospatial API 的应用必须向用户显示提示，以便用户确认并允许使用其设备中的数据。如需了解详情，请参阅用户隐私权要求。

检查设备兼容性

并非所有支持 ARCore 的设备都支持 Geospatial API，如快速入门中所述。

如需检查用户设备的兼容性，请调用 Session.checkGeospatialModeSupported()。如果此方法返回 false，请勿尝试配置会话（见下文），因为这样做会抛出 UnsupportedConfigurationException。

在运行时向用户请求位置信息权限

应用必须在运行时请求位置信息权限。

如需使用 ARCore Geospatial API，您的应用需要注册以下额外权限：

  • ACCESS_FINE_LOCATION，用于准确确定用户的位置。

  • ACCESS_COARSE_LOCATION：用于不准确的用户位置信息，以及遵守用户隐私要求。不过，Geospatial API 无法配置为使用粗略位置信息，并且当用户设置此权限时，API 请求将会失败。如需了解详情，请参阅下文。

  • ACCESS_INTERNET 与 ARCore Geospatial API 服务联系。

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

在搭载 Android 12 或更高版本的设备上，用户可以要求您的应用只能访问大致位置信息。为了满足此请求，您的应用必须配置 ACCESS_COARSE_LOCATION 权限以及 ACCESS_FINE_LOCATION，如上所示。您必须同时配置这两项位置信息权限。

不过，如果用户指定粗略位置，则会导致 Geospatial API 无法获取所需的精确位置。如果您的应用仅提供粗略位置信息，地理空间服务将不允许自行配置。您的应用无法将 Geospatial API 与粗略位置信息搭配使用。

检查设备当前位置的地理空间可用性

由于 Geospatial API 会结合使用 VPS 和 GPS 来确定地理空间姿势，因此只要设备能够确定其位置，就可以使用该 API。在 GPS 精度较低的区域（例如室内空间和密集的城市环境）中，该 API 将依赖于 VPS 覆盖范围来生成高精度姿势。在典型条件下，VPS 的定位精度预计为 5 米左右，旋转精度为 5 度。使用 Session.checkVpsAvailabilityAsync() 确定给定位置是否有 VPS 覆盖。

Geospatial API 还可在未覆盖 VPS 的区域使用。在头顶上方没有或几乎没有遮挡物的室外环境中，GPS 可能就足以生成高精度的姿势。

后续步骤