消费者 SDK 按需行程概览

允许消费者跟踪您为其提供的订单、行程或其他服务的行程，从而为按需行程量身定制消费者体验。

消费者应用跟踪行程

什么是 Consumer SDK？

Consumer SDK 是 Fleet Engine 的一部分，用于按需行程。它提供了一些接口，用于在 Fleet Engine 中对行程数据进行建模并跟踪行程，还提供了一些类，供您创建基于地图的丰富显示界面，以便与消费者用户分享行程。您需要将 Consumer SDK 集成到应用中，并在 Fleet Engine 中设置适当的角色配置文件，以打造这种消费者体验。

借助 Consumer SDK 平台专用 API，您可以将行程分享功能原生构建到应用中。Consumer SDK 适用于以下平台：

为何使用 Consumer SDK？

将 Consumer SDK 集成到按需行程应用中，您可以提供全面的消费者体验，包括近乎实时的位置信息更新和贴合道路的位置。您的消费者可以看到叠加在地图上的车辆路线，包括帮助他们了解行程或配送进度的详细信息。

您可以使用 Consumer SDK 做些什么？

您可以使用 Driver SDK 和 Fleet Engine 中的信息来打造自定义消费者体验，包括以下功能：

  • 自定义地图界面，以满足您的品牌需求。

  • 跟踪车辆沿路线行驶时的当前位置，并定期更新其位置。

  • 显示上车点和下车点的预计到达时间 (ETA)。

  • 显示剩余距离。

  • 显示路线上的实时路况。

Consumer SDK 的运作方式

概括来讲，Consumer SDK 依赖于以下机制：

  • 拥有适当的 Fleet Engine 角色，以便经过身份验证的应用可以跟踪与消费者订单关联的行程。
  • 由您的后端系统提供的消费者与行程之间的关联。
  • TripModel 和 JourneySharingSession SDK 类，用于在消费者应用中对行程数据进行建模并共享行程会话。

Consumer SDK 还提供其他接口和类，以便您创建丰富的应用体验，其中包含路况、地图标记、预计到达时间和路线数据等详细信息。

Consumer SDK 的运作方式

下表显示了消费者应用跟踪的行程流程。

1 消费者应用请求行程 您的后端服务器收到按需行程请求，并执行以下操作：
  • 在 Fleet Engine 中创建行程。
  • 将行程分配给车辆。
2 司机接受行程 司机应用获取行程 ID 和行程信息，司机接受行程。
3 消费者应用请求获取跟踪行程的权限 消费者应用从您的后端获取行程 ID，并请求开始跟踪行程。
4 司机开始行程 当司机使用司机应用指明行程已开始时，该应用会通过 Driver SDK 通知您的后端服务器。 例如，当司机即将离开餐厅或开车前往取餐地点时。
5 Fleet Engine 开始发送行程信息 Fleet Engine 开始跟踪行程，并与消费者应用分享行程进度。
6 消费者应用显示行程信息 消费者应用会通知消费者，并开始向其显示行程信息，同时在行程进行过程中更新行程。
7 行程已取消或已完成 当司机取消或完成行程时，司机应用会停用位置跟踪功能，并且您的后端服务器会告知 Fleet Engine 将行程标记为已取消或已完成。
8 消费者应用停止跟踪行程 行程显示为已取消或已完成。
9 针对下一个行程重复此过程 系统会创建新行程，并重复上述过程。

如何使用 Consumer SDK

选择您的平台，了解如何在消费者应用中开始跟踪行程。

Android

1 在 Android 中设置 Consumer SDK 如需在应用中跟踪按需行程，请设置 Consumer SDK。如需了解详情，请参阅获取 Android 消费端 SDK。
2 设置可视化界面 定义地图并添加对矢量地图的支持，以设置消费者体验。如需了解详情，请参阅设置地图。
3 关注行程 跟踪行程，以便向客户分享相应车辆的位置。如需了解详情，请参阅关注行程。
5 更新行程进度并处理行程错误 更新行程详情，例如行程距离和预计到达时间，并处理行程期间出现的任何错误。如需了解详情，请参阅更新行程进度和处理行程错误。
5 行程结束后，停止关注 停止跟踪行程，以停止与客户分享车辆的位置信息。如需了解详情，请参阅停止关注行程。

iOS

1 在 iOS 中设置 Consumer SDK 如需在应用中跟踪按需行程，请设置 Consumer SDK。如需了解详情，请参阅获取 iOS 消费者 SDK。
2 设置可视化界面 初始化地图视图并处理地图事件，以设置消费者体验。如需了解详情，请参阅设置地图。
3 关注行程 跟踪行程，以便向客户分享相应车辆的位置。如需了解详情，请参阅关注行程。
5 更新行程进度并处理行程错误 更新行程详情（例如行程距离和预计到达时间），并处理行程期间出现的任何错误。如需了解详情，请参阅更新行程进度和处理行程错误。
5 行程结束后，停止关注 停止跟踪行程，以停止与客户分享车辆的位置信息。如需了解详情，请参阅停止关注行程。

JavaScript

1 在 JavaScript 中设置 Consumer SDK 如需在应用中跟踪按需行程，请设置 Consumer SDK。如需了解详情，请参阅设置 JavaScript 消费者 SDK。
2 加载和自定义地图 启用 Maps JavaScript API 并设置授权，以设置消费者体验。如需了解详情，请参阅设置地图。
3 关注行程 跟踪行程，以便向客户分享相应车辆的位置。如需了解详情，请参阅关注行程。
5 更新行程进度并处理行程错误 更新行程的详细信息，例如行程距离和预计到达时间，并处理行程中的任何错误。如需了解详情，请参阅更新和跟踪行程进度以及处理行程错误。
5 行程结束后，停止关注 停止跟踪行程，以停止与客户分享车辆的位置信息。如需了解详情，请参阅停止关注行程。

组件

本部分总结了跟踪行程所需的两个组件：

（可选）您还可以使用以下组件自定义消费者体验：

身份验证令牌提取器

如需控制对 Fleet Engine 中存储的位置数据的访问权限，您必须执行以下操作：

  1. 在服务器上为 Fleet Engine 实现 JSON Web 令牌 (JWT) 创建服务。如需了解详情，请参阅颁发 JWT。

  2. 在 Web 或移动应用中实现身份验证令牌提取器，以对位置数据访问权限进行身份验证。如需详细了解如何设置令牌提取器，请参阅适用于 Android、iOS 或 JavaScript 的设置指南。

地图视图和行程跟踪器

“跟踪行程”包含用于直观呈现车辆和航点的组件，以及用于显示司机预计到达时间或剩余行驶距离的原始数据 Feed。

下表介绍了这些组件：

组件 说明
消费者地图视图 地图视图可管理行程的生命周期，在行程进行过程中显示车辆位置的航点。如果车辆的路线已知，地图视图会更新车辆路线多段线，以指示车辆沿其路线的进度。
JavaScript 中的行程位置信息提供程序 对于 JavaScript Web 应用，行程位置信息提供程序会将所跟踪对象的位置信息馈送到共享行程地图中。如需了解详情，请参阅实例化行程位置信息提供程序。 您可以使用行程位置信息提供程序跟踪行程的以下详细信息：
  • 行程的上车点或下车点。
  • 分配给行程的车辆的位置和路线。

跟踪的位置对象

位置信息提供程序会跟踪航点和车辆等对象的位置，如下表所述。

追踪的位置 说明
上车地点 上车点是行程的起点。
目标位置 目的地位置是行程结束的位置。 它标记了下车地点。
航点位置 航点位置是指所跟踪行程路线上的任何中间位置。从技术上讲，航点可以包括上车点和下车点，但航点通常是指路线上的中间停靠点。例如，配送路线中上车地点和目的地之间的停靠点就是航点位置。如需了解详情，请参阅 Fleet Engine 文档中的行程航点。
车辆位置 车辆位置是指车辆的上报位置。如需了解详情，请参阅 Fleet Engine 文档中的车辆位置。

设置地图样式

标记和多段线样式决定了地图上所跟踪位置对象的外观和风格。您可以使用自定义样式选项来匹配 Web 应用的样式。

控制跟踪地点的公开范围

Fleet Engine 中预定义的位置信息提供程序会针对地图上跟踪的位置对象遵循以下公开范围规则。如果您创建自定义或派生位置信息提供程序，则可以更改公开范围规则。

  • 车辆仅在行程进行期间可见：行程车辆从分配给行程到下车期间可见。如果行程取消，车辆将不再可见。

  • 所有其他位置标记始终可见：出发地、目的地和航点的所有其他位置标记始终显示在地图上。例如，无论行程或配送处于何种状态，行程下车地点或配送地点始终显示在地图上。

后续步骤

请参阅您要跟踪行程的平台对应的文档：