检查设备当前所在位置的 VPS 是否可用

Geospatial API 结合使用 VPS 和 GPS 数据来生成准确度高的地理空间姿势。您可以在设备能够确定其位置的任何位置使用该 API:

  • 在 GPS 准确度较低的区域,例如室内空间和人口密集的城市环境中,该 API 将依靠 VPS 覆盖范围来生成准确度较高的姿势。
  • 在没有高空障碍物或没有上空障碍物的户外环境中,Geospatial API 可以使用可用的 GPS 位置数据,生成准确度高的地理空间姿势。

您可以在 AR 会话启动之前确定 VPS 是否处于给定水平位置,并用它来打造更具体的体验,例如,仅在 VPS 可用时才显示“进入 AR”按钮。

启用 ARCore API

您的应用必须启用 ARCore API 以检查 VPS 可用性。

启用 ARCore API 后,您无需执行以下操作即可检查 VPS 可用性:

检查应用中的 VPS 可用性

Geospatial API 可以在设备能够确定其位置的任何位置使用。如果您的 AR 体验取决于 VPS 覆盖范围,您可以使用 Session.checkVpsAvailabilityAsync() 获取 VpsAvailabilityFuture,这是一个异步任务,用于检查给定水平位置的 VPS 可用性。 获得 VpsAvailabilityFuture 后,您可以通过轮询或回调来获取其结果。

调查结果

使用 Future.getState() 获取 Future 的状态。共有三种状态:

您可以继续检查 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 可能足以生成非常准确的姿势。

后续步骤