借助适用于 Android 的消费者 SDK,您可以使用模块化架构创建拼车应用。您可以使用要用于特定应用的 API 部分,并将它们与您自己的 API 集成。适用于不同功能的 Consumer SDK API 封装在单独的模块中。
如果您的拼车应用使用早期版本的消费者 SDK,您需要升级应用才能使用此模块化架构。本迁移指南介绍了如何升级应用。
概览
Consumer SDK 模块化架构引入了一个会话对象来保存界面状态。在以前的 Consumer SDK 版本中,应用会在状态之间转换。利用这种模块化架构,您可以创建一个 Session 对象,并可以选择在地图上显示该会话。如果未显示任何会话,则地图为空。再也没有“空”或“已初始化”状态。
Session 对象表示模块的单个生命周期使用情况实例。会话是模块 API 的接入点。例如,行程分享会话针对单次行程。您需要与 Session 对象交互以监控行程。
Session 对象与模块类型相关联。Session 对象的行为与用于初始化该对象的对象的生命周期相关。
假设您创建了一个 TripModel
对象来跟踪 TRIP_A。如果您尝试再次获取 TRIP_A 的 TripModel
对象,将会获得相同的 TripModel
对象。如需跟踪 TRIP_B,请获取新的 TripModel
对象。
会话状态
会话可能处于以下几种状态之一:
已创建的会话由 Session 对象表示。通过调用
create
方法创建会话。例如:JourneySharingSession sessionA = JourneySharingSession.createInstance(TripModelA)
系统会注册已启动会话以更新其界面元素的数据和值。通过调用
start
方法启动会话。例如:sessionA.start()
系统会自动开始显示的会话。它会显示界面元素,并根据数据更新进行更新。您可以通过调用
showSession
方法来显示会话。例如:ConsumerController.showSession(sessionA)
已停止刷新的会话会停止刷新数据并停止更新其界面元素。通过调用
stop
方法停止会话。例如:sessionA.stop()
使用仅限数据组件和界面组件
您可以使用纯数据组件或按需行程和配送解决方案提供的界面元素 API 来创建拼车应用。
使用仅包含数据的组件
如需使用纯数据组件创建拼车应用,请执行以下操作:
- 初始化一个
ConsumerApi
对象。 - 从
ConsumerApi
获取TripModelManager
对象。 - 使用
TripModelManager
开始监控行程,以接收TripModel
对象。 - 在
TripModel
对象上注册回调。
以下示例展示了如何使用仅包含数据的组件:
TripModelManager tripManager = ConsumerApi.getTripModelManager();
TripModel tripA = tripManager.getTripModel("trip_A");
tripA.registerTripCallback(new TripModelCallback() {})
使用界面元素 API
使用 ConsumerController
对象访问按需行程和交付解决方案界面元素 API。
如需使用按需行程和配送解决方案界面元素 API 创建拼车应用,请执行以下操作:
- 初始化
ConsumerApi
对象: - 从
ConsumerApi
对象获取TripModelManager
对象。 - 从跟踪一次行程的
TripModelManager
获取TripModel
对象。 - 将
ConsumerMap[View/Fragment]
添加到应用视图中。 - 从
ConsumerMap[View/Fragment]
获取ConsumerController
对象。 - 向 Controller 提供
TripModel
对象以获取JourneySharingSession
对象。 - 使用控制器显示
JourneySharingSession
。
以下示例展示了如何使用界面 API:
TripModelManager tripManager = ConsumerApi.getTripModelManager();
TripModel tripA = TripModelManager.getTripModel("trip_A");
// Session is NOT automatically started when created.
JourneySharingSession jsSessionA = JourneySharingSession.createInstance(tripA);
JourneySharingSession jsSessionB = JourneySharingSession.createInstance(tripB);
// But a session is automatically started when shown.
ConsumerController.showSession(jsSessionA);
ConsumerController.showSession(jsSessionB); // hides trip A; shows trip B.
ConsumerController.hideAllSessions(); // don't show any sessions
// Unregister listeners and delete UI elements of jsSessionA.
consumerController.showSession(jsSessionA);
jsSessionA.stop();
// Recreates and shows UI elements of jsSessionA.
jsSessionA.start();
模块化架构代码更改
如果您的拼车应用使用早期版本的 Consumer SDK,则更新后的模块化架构将需要对代码进行一些更改。本部分介绍了其中的部分更改。
位置权限
Consumer SDK 不再需要 FINE_LOCATION
权限。
行程监控
更新后的模块化架构需要针对数据层和界面用户更改代码。
在早期版本中,数据层用户可能使用以下代码处理行程监控:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
manager.setActiveTrip("trip_id")
manager.registerActiveTripCallback(new TripModelCallback() {})
采用模块化架构时,数据层用户将使用以下代码:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
TripModel tripA = TripModelManager.getTrip("trip_A")
tripA.registerTripCallback(new TripModelCallback() {})
在早期版本中,界面用户可能会使用以下代码处理行程监控:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
manager.setActiveTrip("trip_id")
ConsumerController controller = consumerGoogleMap.getConsumerController();
consumerController.startJourneySharing()
使用模块化架构时,界面用户将使用以下代码:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
TripModel tripA = TripModelManager.getTripModel("trip_A");
ConsumerController controller = consumerGoogleMap.getConsumerController();
JourneySharingSession jsSessionA = JourneySharingSession.createInstance(tripA);
controller.showSession(jsSessionA);
地图重新居中
没有处于活跃状态的会话时,地图视图或 fragment 在初始化时不会再缩放至用户的位置。只要启用了 AutoCamera 功能,应用就会继续自动缩放以显示处于活动状态的行程分享会话。AutoCamera 默认处于启用状态。
在早期版本中,您可以使用以下代码将摄像头居中放置在当前活跃会话的中心:
consumerController.centerMapForState()
采用模块化架构时,您需要使用以下代码:
CameraUpdate cameraUpdate = consumerController.getCameraUpdate()
if (cameraUpdate != null) {
googleMap.animateCamera(cameraUpdate);
// OR googleMap.moveCamera(cameraUpdate);
}
如需在早期版本中停用 AutoCamera 功能,您应使用以下代码:
consumerController.disableAutoCamera(true);
采用模块化架构时,您需要使用以下代码:
consumerController.setAutoCameraEnabled(false);
自定义
按需行程和送货解决方案自定义 FAB 已从地图中移除。
还移除了 FAB 的关联方法:
ConsumerController.isMyLocationFabEnabled()
ConsumerController.setMyLocationFabEnabled()