The Consumer SDK for Android 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 Session 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 Session object and have the option to display the session on the map. If no sessions are shown, the map is blank. There is no longer an "empty" or "initialized" state.
A Session 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 Session object to monitor the trip.
A Session object is associated with a module type. The Session object's behavior is linked to the lifecycle of the object used to initialize it.
Suppose you create a TripModel
object to track TRIP_A.
If you try to obtain a TripModel
object for TRIP_A again, you will
get the same TripModel
object. To track TRIP_B, obtain a new
TripModel
object.
Session states
A session can be in one of several states:
A created session is represented by a Session object. You create a session by calling the
create
method. For example:JourneySharingSession sessionA = JourneySharingSession.createInstance(TripModelA)
A started session is registered for updates to data and values of its user interface elements. You start a session by calling the
start
method. For example:sessionA.start()
A shown session starts automatically. It displays user interface eelements and updates them in response to data updates. You show a session by calling the
showSession
method. For example:ConsumerController.showSession(sessionA)
A stopped session stops refreshing its data and stops updating its user interface elements. You stop a session by calling the
stop
method. For example:sessionA.stop()
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 On-demand Rides and Deliveries Solution.
Using data-only components
To create a ridesharing app using data-only components:
- Initialize a
ConsumerApi
object. - Obtain the
TripModelManager
object from theConsumerApi
. - Start monitoring a trip with the
TripModelManager
to receive aTripModel
object. - Register callbacks on the
TripModel
object.
The following example shows how to use data-only components:
TripModelManager tripManager = ConsumerApi.getTripModelManager();
TripModel tripA = tripManager.getTripModel("trip_A");
tripA.registerTripCallback(new TripModelCallback() {})
Using the user interface element APIs
Use the ConsumerController
object to access
the On-demand Rides and Deliveries Solution user interface element APIs.
To create a ridesharing app with the On-demand Rides and Deliveries Solution user interface element APIs:
- Initialize the
ConsumerApi
object. - Obtain a
TripModelManager
object from theConsumerApi
object. - Obtain a
TripModel
object from theTripModelManager
that tracks one trip. - Add the
ConsumerMap[View/Fragment]
to the application view. - Obtain a
ConsumerController
object from theConsumerMap[View/Fragment]
. - Provide the
TripModel
object to the Controller to obtain aJourneySharingSession
object. - Use the Controller to show the
JourneySharingSession
.
The following example shows how to use the user interface APIs:
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();
Modular architecture code changes
If your Ridesharing app uses earlier versions of the Consumer SDK, the updated modular architecture will require some changes to your code. This section describes some of those changes.
Location permissions
FINE_LOCATION
permissions are no longer required
by the Consumer SDK.
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:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
manager.setActiveTrip("trip_id")
manager.registerActiveTripCallback(new TripModelCallback() {})
Using the modular architecture, a data-layer user would use the following code:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
TripModel tripA = TripModelManager.getTrip("trip_A")
tripA.registerTripCallback(new TripModelCallback() {})
In earlier versions, a user-interface user might handle trip monitoring using the following code:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
manager.setActiveTrip("trip_id")
ConsumerController controller = consumerGoogleMap.getConsumerController();
consumerController.startJourneySharing()
Using the modular architecture, a user-interface user would use the following code:
ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
TripModel tripA = TripModelManager.getTripModel("trip_A");
ConsumerController controller = consumerGoogleMap.getConsumerController();
JourneySharingSession jsSessionA = JourneySharingSession.createInstance(tripA);
controller.showSession(jsSessionA);
Map recentering
The map view or fragment no longer zooms to the user's location on initialization when there is no session active. It will still automatically zoom to show the active Journey Sharing session as long as the AutoCamera feature is enabled. AutoCamera is enabled by default.
In earlier versions, you would use the following code to center the camera for the current active session:
consumerController.centerMapForState()
Using the modular architecture, you would use the following code:
CameraUpdate cameraUpdate = consumerController.getCameraUpdate()
if (cameraUpdate != null) {
googleMap.animateCamera(cameraUpdate);
// OR googleMap.moveCamera(cameraUpdate);
}
To disable the AutoCamera feature in earlier versions, you would use the following code:
consumerController.disableAutoCamera(true);
Using the modular architecture, you would use the following code:
consumerController.setAutoCameraEnabled(false);
Customization
The On-demand Rides and Deliveries Solution custom FAB has been removed from the map.
Associated methods for the FAB have also been removed:
ConsumerController.isMyLocationFabEnabled()
ConsumerController.setMyLocationFabEnabled()