在應用程式中設定 Geospatial API

適用的 XR 裝置

本指南可協助您為這類 XR 裝置打造體驗。

瞭解 XR 裝置類型 →

瞭解 XR 裝置類型 →

如要在應用程式中使用 Geospatial API，您必須設定應用程式，以便存取 Google Cloud 上的 ARCore API。這個 API 包含視覺定位服務，可使用 Google 街景服務的資料提供精確定位。

本指南將協助您設定 Google Cloud 雲端專案，並啟用正確的 API 和授權方法，以便存取 API。

設定 Google Cloud 專案或使用現有專案

如果您已有 Google Cloud 雲端專案，請選取該專案。

前往專案選取器

如果沒有現有專案，請建立一個。

建立新專案

啟用 ARCore API

如要使用 ARCore API，您必須在專案中啟用該 API。

啟用 ARCore API

設定 Google Cloud 授權

Android 應用程式可使用兩種授權方法與 ARCore API 通訊：無金鑰授權 (OAuth 2.0，建議方法) 和 API 金鑰授權：

• 無金鑰授權會結合應用程式的套件名稱和簽署金鑰的指紋，為應用程式授權。

• API 金鑰是用於識別 Google Cloud 專案的字串。API 金鑰通常不安全，因為用戶端通常可以存取。建議使用無金鑰授權與 ARCore API 通訊。

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

要求必要權限

如要在 ARCore 中搭配 Jetpack XR 使用 Geospatial API，應用程式必須要求下列執行階段權限：

• ACCESS_FINE_LOCATION：用於判斷使用者的精確位置。

在行動裝置上，Geospatial API 還需要下列權限：

• android.permission.CAMERA：存取裝置相機的必要權限。
• android.permission.INTERNET：與 Google Cloud 服務通訊時必須使用。

存取工作階段

透過 Jetpack XR 執行階段 Session 存取地理空間資訊，應用程式必須建立該執行階段。

設定工作階段

根據預設，XR 工作階段不會啟用 Geospatial API。應用程式必須在 Session 上設定 GeospatialMode，明確啟用這項功能。可用模式如下：

• GeospatialMode.SPATIAL：Geospatial API 已啟用。Geospatial API 會使用視覺定位系統 (VPS)、全球定位系統 (GPS) 資料，以及裝置的動作感應器，判斷裝置的地理空間姿勢。智慧型眼鏡裝置不支援這個模式。
• GeospatialMode.INERTIAL：在省電模式下啟用 Geospatial API。Geospatial API 只會使用 GPS 和裝置的動作感應器，判斷裝置的地理空間姿勢。這個模式僅適用於智慧眼鏡裝置。
• GeospatialMode.DISABLED：停用 Geospatial API。從其他模式轉換至這個模式時，Geospatial API 會釋出所有取得的資源，並停止追蹤。

並非所有裝置都支援所有地理空間模式。詳情請參閱 GeospatialMode。使用 XrDevice.isGeospatialSupported 檢查是否支援指定的 GeospatialMode。

下列程式碼範例示範如何使用 Session.configure 設定 GeospatialMode。

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}
Setup.kt

提示使用者允許使用裝置資料

如果應用程式搭配 ARCore for Jetpack XR 使用 Geospatial API，必須向使用者顯示提示，確認並允許使用裝置資料。詳情請參閱使用者隱私權規定。

使用 Geospatial 物件

設定工作階段後，請使用 Geospatial.getInstance 取得 Geospatial 物件。只有在 Geospatial 物件的狀態為 GeospatialTrackingState.RUNNING 時，才能使用該物件。

下列程式碼範例示範如何使用 Geospatial.state 監控地理空間狀態。

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}
Setup.kt

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}
Setup.kt

瞭解準確度值

啟用 Geospatial API 後，系統會提供三個精確度值：水平、垂直和方向精確度。這些準確度值會隨著時間更新，並隨著取得更多資料而變得更精確。值越大，表示準確度越低，定義為 68% 信賴水準的半徑。換句話說，實際值有 68% 的機率落在預估值的指定半徑範圍內。

使用 Geospatial.State.horizontalAccuracy、verticalAccuracy 和 orientationYawAccuracy 取得目前的準確度值。

應用程式可能需要特定精確度才能正常運作。舉例來說，應用程式可能會等到水平精確度小於 5 公尺，才算繪虛擬內容。為提高取得高準確度資料的可能性，應用程式應指示使用者環顧四周，最好是 Google 街景服務中具有高視覺細節的建築物或其他特徵。使用 Geospatial.checkVpsAvailability 判斷指定位置是否可使用 VPS。

後續步驟

在應用程式中正確設定 Geospatial API 後，應用程式就能執行下列操作：

• 在裝置本機姿勢和地理空間姿勢之間轉換
• 在地理空間姿勢算繪內容