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

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

前提条件

确保您了解 AR 基本概念 以及如何在继续之前配置 ARCore 现场录像。

示例应用和 Codelab

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

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

请参阅 Geospatial API 简介，了解详情 有关 Geospatial API 的信息。

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

请确保您的开发环境满足 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 可能足以生成高精度姿势。

后续步骤