在 Android 设备上跟踪行程

请选择平台： Android iOS JavaScript

当您跟踪行程时，您的消费者应用会显示 向消费者展示合适的车辆。为此，您的应用需要 跟踪行程，更新行程进度，并在该行程发生时停止跟踪 。

本文档介绍了该流程的工作原理。

准备工作

确保您已设置以下各项：

  • 消费者应用的后端服务已就位，且您的服务已就绪 让消费者与车辆匹配。

  • 您已为应用设置地图。

开始跟踪行程

当您的后端服务器将消费者与车辆进行匹配时， JourneySharingSession开始使用行程分享功能跟踪行程。

以下示例代码演示了如何在 视图加载。

Java

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Create a TripModel instance to listen for updates to the trip specified by this trip name.
    String tripName = ...;
    TripModelManager tripModelManager = consumerApi.getTripModelManager();
    TripModel tripModel = tripModelManager.getTripModel(tripName);

    // Create a JourneySharingSession instance based on the TripModel.
    JourneySharingSession session = JourneySharingSession.createInstance(tripModel);

    // Add the JourneySharingSession instance on the map for updating the UI.
    consumerController.showSession(session);

    // Register for trip update events.
    tripModel.registerTripCallback(new TripModelCallback() {
      @Override
      public void onTripETAToNextWaypointUpdated(
          TripInfo tripInfo, @Nullable Long timestampMillis) {
        // ...
      }

      @Override
      public void onTripActiveRouteRemainingDistanceUpdated(
          TripInfo tripInfo, @Nullable Integer distanceMeters) {
        // ...
      }

      // ...
    });
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();

    if (journeySharingSession != null) {
      journeySharingSession.stop();
    }
  }
}

Kotlin

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Create a TripModel instance to listen for updates to the trip specified by this trip name.
    val tripName = "tripName"
    val tripModelManager = consumerApi.getTripModelManager()
    val tripModel = tripModelManager.getTripModel(tripName)

    // Create a JourneySharingSession instance based on the TripModel.
    val session = JourneySharingSession.createInstance(tripModel)

    // Add the JourneySharingSession instance on the map for updating the UI.
    consumerController.showSession(session)

    // Register for trip update events.
    tripModel.registerTripCallback(
      object : TripModelCallback() {
        override fun onTripETAToNextWaypointUpdated(
          tripInfo: TripInfo,
          timestampMillis: Long?,
        ) {
          // ...
        }

        override fun onTripActiveRouteRemainingDistanceUpdated(
          tripInfo: TripInfo,
          distanceMeters: Int?,
        ) {
          // ...
        }

      // ...
    })
  }

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

更新行程进度

更新行程进度详情，例如车辆到达的距离 行程和预计到达时间时，您的应用需要 注册和配置监听器，如以下示例所示。

  1. 在 TripModel 对象上注册监听器。

    Java

    // Create a TripModel instance for listening to updates to the trip specified by this trip name.
String tripName = ...;
TripModelManager tripModelManager = consumerApi.getTripModelManager();
TripModel tripModel = tripModelManager.getTripModel(tripName);

// Create a JourneySharingSession instance based on the TripModel.
JourneySharingSession session = JourneySharingSession.createInstance(tripModel);

// Add the JourneySharingSession instance on the map for updating the UI.
consumerController.showSession(session);

// Register for trip update events.
tripModel.registerTripCallback(new TripModelCallback() {
@Override
public void onTripETAToNextWaypointUpdated(
        TripInfo tripInfo, @Nullable Long timestampMillis) {
      // ...
}

@Override
public void onTripActiveRouteRemainingDistanceUpdated(
        TripInfo tripInfo, @Nullable Integer distanceMeters) {
      // ...
}

// ...
});

    Kotlin

    // Create a TripModel instance for listening to updates to the trip specified by this trip name.
val tripName = "tripName"
val tripModelManager = consumerApi.getTripModelManager()
val tripModel = tripModelManager.getTripModel(tripName)

// Create a JourneySharingSession instance based on the TripModel.
val session = JourneySharingSession.createInstance(tripModel)

// Add the JourneySharingSession instance on the map for updating the UI.
consumerController.showSession(session)

// Register for trip update events.
tripModel.registerTripCallback(
  object : TripModelCallback() {
    override fun onTripETAToNextWaypointUpdated(
      tripInfo: TripInfo,
      timestampMillis: Long?,
    ) {
      // ...
    }

    override fun onTripActiveRouteRemainingDistanceUpdated(
      tripInfo: TripInfo,
      distanceMeters: Int?,
    ) {
      // ...
    }

  // ...
})

  2. 使用 TripModelOptions 配置行程的监听器。

    Java

    // Set refresh interval to 2 seconds.
TripModelOptions tripOptions =
      TripModelOptions.builder().setRefreshIntervalMillis(2000).build();
tripModel.setTripModelOptions(tripOptions);

    Kotlin

    // Set refresh interval to 2 seconds.
val tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build()
tripModel.setTripModelOptions(tripOptions)

停止关注行程

确保您的应用在不再需要某行程时停止跟踪该行程，例如 因为驾驶员在后端将行程标记为“COMPLETE”。停止旅程 共享可避免向 Fleet Engine 发送不必要的网络请求，并可避免内存不足 泄漏。

使用 JourneySharingSession 停止跟踪行程，如 示例代码。

Java

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

  @Override
  protected void onDestroy() {
    super.onDestroy();

    if (journeySharingSession != null) {
      journeySharingSession.stop();
    }
  }
}

Kotlin

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

处理行程错误

onTripRefreshError 方法会显示行程期间发生的错误 监控。错误消息遵循 Google Cloud 错误标准。如需详细了解 错误消息定义以及所有错误代码，请参阅 Google Cloud 错误 文档。

以下是行程监控期间可能发生的一些常见错误：

HTTP RPC 说明
400 INVALID_ARGUMENT 客户指定的行程名称无效。行程名称必须遵循 格式为 providers/{provider_id}/trips/{trip_id}。通过 provider_id 必须是所有者为 Cloud 的 Cloud 项目的 ID， 服务提供商
401 UNAUTHENTICATED 如果没有有效的身份验证凭据，您会收到此错误。 例如，在 JWT 令牌签名时不含行程 ID 或 JWT 令牌 已过期。
403 PERMISSION_DENIED 如果客户端权限不足，您会收到此错误 （例如，具有使用方角色的用户尝试调用 updateTrip），如果 JWT 令牌无效，或者客户端项目未启用该 API。 可能缺少 JWT 令牌，或者令牌已用行程 ID 签名， 与请求的行程 ID 不匹配。
429 RESOURCE_EXHAUSTED 资源配额为零或流量超出限制。
503 UNAVAILABLE 服务不可用。通常是服务器已关闭。
504 DEADLINE_EXCEEDED 超出请求时限。只有在调用方设置了 比方法的默认截止期限短（即 请求的截止时间不足以让服务器处理请求）且 请求未在期限内完成。

处理使用方 SDK 错误

消费者 SDK 使用回调向消费者应用发送行程更新错误 机制。回调参数是平台特定的返回值类型 ( TripUpdateError 以及 NSError ）。

提取状态代码

传递给回调函数的错误通常是 gRPC 错误，您也可以 从它们提取额外信息。对于 状态代码的完整列表，请参阅 状态代码及其在 gRPC 中的使用。

Java

您可以提取提供错误详细信息的 gRPC 状态代码 （从 onTripUpdateError() 返回的 TripUpdateError 中）。

// Called when there is a trip update error.
@Override
public void onTripUpdateError(TripInfo tripInfo, TripUpdateError error) {
  Status.Code code = error.getStatusCode();
}

Kotlin

您可以提取提供错误详细信息的 gRPC 状态代码 （从 onTripUpdateError() 返回的 TripUpdateError 中）。

// Called when there is a trip update error.
override fun onTripUpdateError(tripInfo: TripInfo, error: TripUpdateError) {
  val code = error.getStatusCode()
}

解读状态代码

状态代码涵盖两种错误：与服务器和网络相关的错误，以及 错误。

服务器和网络连接错误

以下状态代码针对的是网络错误或服务器错误， 无需采取任何措施来解决这些问题。使用方 SDK 会自动 能够从中恢复

状态代码说明
ABORTED 服务器已停止发送响应。这通常是由 服务器问题。
已取消 服务器终止了外发响应。这通常 发生以下情况：
当应用被发送到后台时，或者当
消费者应用。
INTERRUPTED
DEADLINE_EXCEEDED 服务器响应时间过长。
UNAVAILABLE 服务器不可用。这通常是由网络所致 问题。

客户端错误

以下状态代码针对的是客户端错误，您必须采取措施 并加以解决。Consumer SDK 会继续重新尝试刷新行程，直到您 结束旅程分享，但在您采取行动后才能恢复。

状态代码说明
INVALID_ARGUMENT 消费者应用指定的行程名称无效；行程名称必须 请遵循 providers/{provider_id}/trips/{trip_id} 格式。
NOT_FOUND 此行程从未创建。
PERMISSION_DENIED 消费者应用的权限不足。出现此错误的情况包括：
  • 消费者应用没有权限
  • Google Cloud 中的项目未启用使用方 SDK 控制台。
  • JWT 令牌缺失或无效。
  • JWT 令牌的签名行程 ID 与 请求的行程。
RESOURCE_EXHAUSTED 资源配额为零，或者流量的速率超过 限速。
UNAUTHENTICATED 由于 JWT 令牌无效，请求未通过身份验证。这个 如果 JWT 令牌签名时不含行程 ID，则会发生错误；或者 在 JWT 令牌过期时触发。