檢查裝置的 VPS 可用性'；目前位置

Geospatial API 結合 VPS 和 GPS 資料，產生高精確度的地理空間姿勢。您可以在裝置能夠判斷其位置的任何位置使用此 API：

• 在 GPS 準確度較低的地區 (例如室內空間和人口稠密的都市環境)，API 會透過 VPS 覆蓋範圍產生高精確度姿勢。
• 在幾乎沒有或完全沒有障礙物的戶外環境中，Geospatial API 或許能使用可用的 GPS 位置資料，以高精確度產生地理空間姿勢。

你可以在 AR 工作階段開始前，在特定水平位置決定 VPS 可用性，並據此打造更具體的體驗，例如顯示「進入 AR」模式按鈕。

啟用 ARCore API

應用程式必須啟用 ARCore API 才能檢查 VPS 可用性。

啟用 ARCore API 後，不必執行下列操作，就能檢查 VPS 可用性：

• 目前執行中的 Session (在呼叫 Session.resume() 之前)。
• 設定 GeospatialMode。

檢查應用程式中的 VPS 可用性

Geospatial API 可用於裝置能夠判斷其位置的任何位置。如果 AR 體驗以 VPS 涵蓋率為依據，可以使用 Session.checkVpsAvailabilityAsync() 取得 VpsAvailabilityFuture，這項非同步工作會檢查特定水平位置的 VPS 可用性。 取得 VpsAvailabilityFuture 後，您可以透過輪詢或回呼取得結果。

對結果進行意見調查

使用 Future.getState() 取得 Future 的狀態。狀態共有三種：

• PENDING：作業尚未完成，因此無法取得任何結果。
• CANCELLED：Future.cancel() 已取消作業。系統一律不會呼叫任何已註冊的回呼。
• DONE：作業已完成。使用 VpsAvailabilityFuture.getResult() 取得結果。

你可以繼續查看 Future.getState()，直到工作完成為止。

Java

// Obtain a VpsAvailabilityFuture and store it somewhere.
VpsAvailabilityFuture future = session.checkVpsAvailabilityAsync(latitude, longitude, null);

// Poll VpsAvailabilityFuture later, for example, in a render loop.
if (future.getState() == FutureState.DONE) {
  switch (future.getResult()) {
    case AVAILABLE:
      // VPS is available at this location.
      break;
    case UNAVAILABLE:
      // VPS is unavailable at this location.
      break;
    case ERROR_NETWORK_CONNECTION:
      // The external service could not be reached due to a network connection error.
      break;

      // Handle other error states, e.g. ERROR_RESOURCE_EXHAUSTED, ERROR_INTERNAL, ...
  }
}

Kotlin

// Obtain a VpsAvailabilityFuture and store it somewhere.
val future = session.checkVpsAvailabilityAsync(latitude, longitude, null)

// Poll VpsAvailabilityFuture later, for example, in a render loop.
if (future.state == FutureState.DONE) {
  when (future.result) {
    VpsAvailability.AVAILABLE -> {
      // VPS is available at this location.
    }
    VpsAvailability.UNAVAILABLE -> {
      // VPS is unavailable at this location.
    }
    VpsAvailability.ERROR_NETWORK_CONNECTION -> {
      // The external service could not be reached due to a network connection error.
    }
    else -> {
      TODO("Handle other error states, e.g. ERROR_RESOURCE_EXHAUSTED, ERROR_INTERNAL, ...")
    }
  }
}

透過回呼取得結果

您也可以透過回呼取得 Future 的結果。使用 Session.checkVpsAvailabilityAsync() 並提供 callback。Future 狀態變成 DONE 後，系統就會在主執行緒上呼叫這個 callback。

Java

session.checkVpsAvailabilityAsync(
    latitude,
    longitude,
    result -> {
      // Callback is called on the Main thread.
      switch (result) {
          // Handle the VpsAvailability result as shown above.
          // For example, show UI that enables your AR view.
      }
    });

Kotlin

session.checkVpsAvailabilityAsync(latitude, longitude) { result ->
  // Callback is called on the Main thread.

  // Handle the VpsAvailability result as shown above.
  // For example, show UI that enables your AR view.
  TODO("Handle VpsAvailability " + result)
}

取消Future

使用 Future.cancel() 可嘗試取消 Future。基於執行緒平行處理的關係，取消嘗試可能並未成功。 如果這次嘗試成功，Future.cancel() 會傳回 true，否則會傳回 false。

在沒有 VPS 涵蓋範圍的情況下使用 Geospatial API

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

後續步驟

• 取得裝置攝影機的地理空間姿勢，藉此判斷使用者裝置的實際位置。