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

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

• 如果是 GPS 精確度偏低的區域 (例如室內空間和人口密集的都市環境)，API 就會仰賴 VPS 覆蓋範圍來產生高精確度姿勢。
• 在幾乎沒有高架障礙的戶外環境中，地理空間 API 或許能夠使用現有的 GPS 位置資料，製作出精準的地理空間姿勢。

你可以在 AR 工作階段開始前以特定水平位置判斷 VPS 適用情形，並使用這項功能打造更精準的體驗，舉例來說，只有在 VPS 可用時才會顯示「進入 AR」按鈕。

啟用 ARCore API

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

啟用 ARCore API 後，即可檢查 VPS 可用性，但這不會：

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

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

地理空間 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。

使用地理空間 API，且未涵蓋 VPS 涵蓋範圍

地理空間 API 也可用於沒有 VPS 涵蓋範圍的區域。在幾乎沒有俯瞰障礙的戶外環境中，GPS 可能足以產生具有高準確度的姿勢。

後續步驟

• 取得裝置相機的地理空間姿勢，判斷使用者裝置在實際位置。