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

Migration for Android Consumer SDK Modularization

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 the ConsumerApi.
Start monitoring a trip with the TripModelManager to receive a TripModel 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 the ConsumerApi object.
Obtain a TripModel object from the TripModelManager that tracks one trip.
Add the ConsumerMap[View/Fragment] to the application view.
Obtain a ConsumerController object from the ConsumerMap[View/Fragment].
Provide the TripModel object to the Controller to obtain a JourneySharingSession 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.

Custom FAB

Associated methods for the FAB have also been removed:

ConsumerController.isMyLocationFabEnabled()
ConsumerController.setMyLocationFabEnabled()