iOS 消费者 SDK 模块化迁移

借助适用于 iOS 的消费者 SDK，您可以使用模块化架构创建拼车应用。您可以使用要用于特定应用的 API 部分，并将它们与您自己的 API 集成。适用于不同功能的 Consumer SDK API 封装在单独的模块中。

如果您的拼车应用使用早期版本的消费者 SDK，您需要升级应用才能使用此模块化架构。本迁移指南介绍了如何升级应用。

概览

Consumer SDK 模块化架构引入了一个 MapViewSession 对象来保存界面状态。在以前的 Consumer SDK 版本中，应用会在状态之间转换。使用此模块化架构，您可以创建一个 MapViewSession 对象，并且可以选择在地图上显示会话。如果未显示任何会话，则地图显示的内容与仅使用 Maps SDK for iOS 时相同。

MapViewSession 对象表示模块的单个生命周期使用情况实例。会话是模块 API 的接入点。例如，行程分享会话针对单次行程。您需要与 JourneySharingSession 对象交互以监控行程。

TripModel 对象

在以前的 Consumer SDK 版本中，TripService 实例仅允许您一次监控一个实时行程。通过使用 TripModel 对象，您可以在一个 TripService 实例中监控多个实时行程。可以从 TripService 创建 TripModel 的实例，并且 TripModel 的每个实例都绑定到特定行程。

如果已注册的订阅者在行程中更新，TripModel 实例会调用更新事件。

TripModel 对象还可用于创建 JourneySharingSession 对象的实例。

MapViewSession 个州

一次只能在一个 mapView 中添加 MapViewSession 实例，它可以处于以下两种状态之一：

  • GMTCMapViewSessionStateInactive 状态表示此 MapViewSession 尚未添加到任何 mapView，或者已从 mapView 中移除。从 mapView 中移除 MapViewSession 实例后，系统会调用 didRemoveFromMapView 方法。

    调用 hideMapViewSession 或 hideAllMapViewSessions 方法会从 mapView 中移除 mapViewSession：

    [_mapView hideMapViewSession:mapViewSessionA];

    或

    [_mapView hideAllMapViewSessions];

  • GMTCMapViewSessionStateActive 状态表示此 MapViewSession 已添加到 mapView。将 MapViewSession 的实例添加到 mapView 后，系统会调用 didAddToMapView 方法。调用 showMapViewSession 方法会将 mapViewSession 添加到目标 mapView：

    [_mapView showMapViewSession:mapViewSessionA];

使用仅限数据组件和界面组件

您可以使用纯数据组件或按需行程和送货解决方案提供的界面元素 API 来创建拼车应用。

使用仅包含数据的组件

如需使用纯数据组件创建拼车应用，请执行以下操作：

  1. 通过指定提供方 ID 和访问令牌提供方来初始化 GMTCServices 对象。
  2. 从 GMTCServices 对象的共享实例获取 tripService 属性。
  3. 使用 tripService 对象的 tripModelForTripName 方法为指定行程创建或检索 GMTCTripModel 对象的实例。
  4. 为 GMTCTripModel 实例注册回调以开始监控行程。

以下示例展示了如何使用仅包含数据的组件：

[GMTCServices setAccessTokenProvider:[[AccessTokenProvider alloc] init]
                          providerID:yourProviderID];
GMTCTripService *tripService = [GMTCServices sharedServices].tripService;

// Create a tripModel instance for listening to updates to the trip specified by this trip name.
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];

// Register for the trip update events.
[tripModel registerSubscriber:self];

// To stop listening for the trip update.
[tripModel unregisterSubscriber:self];

使用界面元素 API

请按照以下步骤创建使用按需行程和配送解决方案界面元素 API 的消费者应用：

  1. 通过指定提供方 ID 和访问令牌提供方来初始化 GMTCServices 对象。
  2. 初始化用于渲染基本地图的 GMTCMapView 对象。
  3. 从 GMTCServices 对象的共享实例获取 tripService 属性。
  4. 使用 tripService 对象的 tripModelForTripName 方法为指定行程创建或检索 GMTCTripModel 对象的实例。
  5. 使用 GMTCTripModel 实例创建 GMTCJourneySharingSession 对象。
  6. 在 mapView 上显示 GMTCJourneySharingSession 对象。
  7. 为 GMTCTripModel 实例注册回调以开始监控行程。

以下示例展示了如何使用界面 API：

[GMTCServices setAccessTokenProvider:[[AccessTokenProvider alloc] init]
                          providerID:yourProviderID];
GMTCTripService *tripService = [GMTCServices sharedServices].tripService;

// Create a tripModel instance for listening to updates to the trip specified by this trip name.
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];
GMTCJourneySharingSession *journeySharingSession =
  [[GMTCJourneySharingSession alloc] initWithTripModel:tripModel];

// Add the journeySharingSession instance on the mapView for UI updating.
[self.mapView showMapViewSession:journeySharingSession];

// Register for the trip update events.
[tripModel registerSubscriber:self];

// To remove the JourneySharingSession from the mapView:
[self.mapView hideMapViewSession:journeySharingSession];

// To stop listening for the trip update.
[tripModel unregisterSubscriber:self];

模块化架构代码更改

如果您的拼车应用使用的是早期版本的 Consumer SDK，则更新后的模块化架构需要对代码进行一些更改。本部分介绍了其中的部分更改。

行程监控

更新后的模块化架构需要针对数据层和界面用户更改代码。

在早期版本中，数据层用户可能使用以下代码处理行程监控：

GRCTripRequest *tripRequest =
    [[GRCTripRequest alloc] initWithRequestHeader:[GRSRequestHeader defaultHeader]
                                         tripName:tripName
                          autoRefreshTimeInterval:1];
GRCTripService *tripService = [GRCServices sharedServices].tripService;
[tripService registerServiceSubscriber:self];
[tripService setActiveTripWithRequest:tripRequest];

采用模块化架构时，数据层用户将使用以下代码：

GMTCTripService *tripService = [GMTCServices sharedServices].tripService;
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];
tripModel.options.autoRefreshTimeInterval = 1;
[tripModel registerSubscriber:self];

在早期版本中，界面用户可能会使用以下代码处理行程监控：

// Show the Journey Sharing user interface.
[self.mapView startTripMonitoring];

// Hide the Journey Sharing user interface.
[self.mapView resetCustomerState];

使用模块化架构时，界面用户将使用以下代码：

// Show the Journey Sharing user interface.
GMTCJourneySharingSession *journeySharingSession =
  [[GMTCJourneySharingSession alloc] initWithTripModel:tripModel];
[self.mapView showMapViewSession:journeySharingSession];

// Hide the Journey Sharing user interface.
[self.mapView hideMapViewSession:journeySharingSession];