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

調整應用程式的設定，讓應用程式使用 Geospatial API。

必要條件

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

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

這部影片會逐步說明如何建構顯示地理空間資訊的應用程式 並運用 Geospatial API，將內容放在實際位置。

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

詳情請參閱 詳情請參閱「Geospatial API 簡介」一文 Geospatial API 的相關資訊。

如果您是第一次使用 ARCore 進行開發，請參閱入門指南 瞭解軟體和硬體需求、先決條件及 您使用的平台專屬其他資訊

請確認您的開發環境符合 ARCore SDK 需求。 如快速入門導覽課程中所述。

啟用 ARCore API

在應用程式中使用視覺定位系統 (VPS) 之前，您必須先 啟用 ARCore API 建立新的叢集或開啟現有 Google Cloud 專案這項服務負責 託管、儲存及解決地理空間錨點。

偏好無金鑰授權，但也支援 API 金鑰授權。

將必要的程式庫新增至應用程式

授權應用程式呼叫 ARCore API 後，您必須將程式庫新增至 在應用程式中啟用地理空間功能。

在應用程式的 build.gradle 檔案中設定 Google Play 服務，將 Google 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 結合 VPS 和 GPS 來確定地理空間姿勢，只要裝置能夠判斷位置，即可使用這個 API。在 GPS 準確度較低的地區 (例如室內空間和人口稠密的都市環境)，API 會透過 VPS 覆蓋範圍產生高精確度的姿勢。在一般情況下，VPS 可提供的位置準確度約為 5 公尺，旋轉準確率為 5 度。使用 Session.checkVpsAvailabilityAsync() 判斷特定位置是否涵蓋 VPS 涵蓋範圍。

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

後續步驟