為 Android 應用程式啟用地理空間 API (Kotlin/Java)

設定應用程式，讓應用程式能夠使用 Geospatial API。

必要條件

請務必先瞭解基本 AR 概念，以及如何設定 ARCore 工作階段，再繼續操作。

範例應用程式和程式碼研究室

這部影片將逐步說明如何建構應用程式，以便顯示地理空間資料，並使用 Geospatial API 將內容放置在實際地點。

您也可以按照地理空間程式碼研究室說明文件中的步驟操作。如要執行影片中建立的範例應用程式，請參閱 ARCore 地理空間快速入門。

如要進一步瞭解 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。

如要檢查使用者的裝置相容性，請呼叫 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 涵蓋範圍。

地理空間 API 也適用於未涵蓋 VPS 的區域。在幾乎沒有或完全沒有障礙物的戶外環境中，GPS 可能足以產生高精確度的姿勢。

後續步驟