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

配置应用设置，以使用 Geospatial API。

前提条件

确保您了解基本 AR 概念以及如何配置 ARCore 会话，然后再继续。

示例应用和 Codelab

本视频逐步介绍了如何构建使用 Geospatial API 显示地理空间数据并将内容放置在实际位置的应用。

您还可以按照 Geospatial Codelab 文档执行相同的步骤。如需运行视频中创建的示例应用，请参阅 ARCore Geospatial 快速入门。

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

如果您是第一次使用 ARCore 进行开发，请参阅使用入门，了解软件和硬件要求、前提条件以及您使用的平台特有的其他信息。

确保您的开发环境满足 ARCore SDK 要求，如快速入门中所述。

启用 ARCore API

在您的应用中使用视觉定位系统 (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 时，应用可以从视觉定位系统 (VPS) 获取地理位置信息。

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

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

检查设备兼容性

并非所有支持 ARCore 的设备也支持 Geospatial API，如quickstart中所述。

如需检查用户设备的兼容性，请调用 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 可能足以生成非常准确的姿势。

后续步骤