On-demand Rides and Deliveries Solution is currently available only to select partners.

Migration for iOS Consumer SDK Modularization

The Consumer SDK for iOS lets you create Ridesharing apps using a modular architecture. You can use the parts of the API that you want to use for your particular app, and integrate them with your own APIs. The Consumer SDK APIs for different features are encapsulated into separate modules.

If your Ridesharing app uses earlier versions of the Consumer SDK, you will need to upgrade your app to use this modular architecture. This migration guide describes how to upgrade your app.

Overview

The Consumer SDK modular architecture introduces a MapViewSession object that holds the user interface state. In previous versions of the Consumer SDK, apps flowed between states. With this modular architecture, you create a MapViewSession object and have the option to display the session on the map. If no sessions are shown, the map displays the same content as only using the Maps SDK for iOS.

A MapViewSession object represents a single lifecycle usage instance of a module. Sessions are the access points into module APIs. For example, a Journey Sharing session follows a single trip. You interact with the JourneySharingSession object to monitor the trip.

`TripModel` object

In previous versions of the Consumer SDK, a TripService instance let you monitor only one live trip at a time. By using a TripModel object, you can monitor multiple live trips in one TripService instance. An instance of the TripModel can be created from the TripService, and each instance of the TripModel is bound to a specific trip.

The TripModel instance calls update events if a registered subscriber is on the trip when it is updated.

The TripModel object can also be used to create an instance of the JourneySharingSession object.

`MapViewSession` states

A MapViewSession instance can be added in only one mapView at a time, and it can be in one of the following two states:

GMTCMapViewSessionStateInactive state indicates that this MapViewSession has either not yet been added to any mapView, or that it has been removed from a mapView. When the MapViewSession instance has been removed from a mapView, the didRemoveFromMapView method is called.

Calling the hideMapViewSession or hideAllMapViewSessions method removes the mapViewSession from a mapView:
```
[_mapView hideMapViewSession:mapViewSessionA];
```
or
```
[_mapView hideAllMapViewSessions];
```
GMTCMapViewSessionStateActive state indicates that this MapViewSession has been added to a mapView. When an instance of the MapViewSession has been added to a mapView, the didAddToMapView method is called. Calling the showMapViewSession method adds the mapViewSession to the target mapView:
```
[_mapView showMapViewSession:mapViewSessionA];
```

Using data-only and user interface components

You can create a ridesharing app using either data-only components or the user interface element APIs provided by the On-demand Rides and Deliveries Solution.

Using data-only components

To create a ridesharing app using data-only components:

Initialize a GMTCServices object by specifying the provider ID and the access token provider.
Obtain the tripService property from the shared instance of the GMTCServices object.
Create or retrieve an instance of a GMTCTripModel object for a specified trip using the tripModelForTripName method of the tripService object.
Register callbacks for the GMTCTripModel instance to start trip monitoring.

The following example shows how to use data-only components:

[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];

Using the UI element APIs

Follow this procedure to create a Consumer app with On-demand Rides and Deliveries Solution user interface element APIs:

Initialize a GMTCServices object by specifying the provider ID and the access token provider.
Initialize a GMTCMapView object for rendering the base map.
Obtain the tripService property from the shared instance of the GMTCServices object.
Create or retrieve an instance of a GMTCTripModel object for a specified trip using the tripModelForTripName method of the tripService object.
Create a GMTCJourneySharingSession object with the GMTCTripModel instance.
Show the GMTCJourneySharingSession object on the mapView.
Register callbacks for the GMTCTripModel instance to start trip monitoring.

The following example shows how to use the user interface APIs:

[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];

Modular architecture code changes

If your Ridesharing app uses earlier versions of the Consumer SDK, the updated modular architecture requires some changes to your code. This section describes some of those changes.

Trip monitoring

The updated modular architecture requires code changes for both data-layer and user-interface users.

In earlier versions, a data-layer user might handle trip monitoring using the following code:

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

Using the modular architecture, a data-layer user would use the following code:

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

In earlier versions, a user-interface user might handle trip monitoring using the following code:

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

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

Using the modular architecture, a user-interface user would use the following code:

// 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];