迁移 Android 消费者 SDK 模块化

借助适用于 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

还移除了 FAB 的关联方法:

ConsumerController.isMyLocationFabEnabled()
ConsumerController.setMyLocationFabEnabled()