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 thisMapViewSession
has either not yet been added to anymapView
, or that it has been removed from amapView
. When theMapViewSession
instance has been removed from amapView
, thedidRemoveFromMapView
method is called.Calling the
hideMapViewSession
orhideAllMapViewSessions
method removes themapViewSession
from amapView
:[_mapView hideMapViewSession:mapViewSessionA];
or
[_mapView hideAllMapViewSessions];
GMTCMapViewSessionStateActive
state indicates that thisMapViewSession
has been added to amapView
. When an instance of theMapViewSession
has been added to amapView
, thedidAddToMapView
method is called. Calling theshowMapViewSession
method adds themapViewSession
to the targetmapView
:[_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 theGMTCServices
object. - Create or retrieve an instance of a
GMTCTripModel
object for a specified trip using thetripModelForTripName
method of thetripService
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 theGMTCServices
object. - Create or retrieve an instance of a
GMTCTripModel
object for a specified trip using thetripModelForTripName
method of thetripService
object. - Create a
GMTCJourneySharingSession
object with theGMTCTripModel
instance. - Show the
GMTCJourneySharingSession
object on themapView
. - 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];