When you use Fleet Engine journey sharing for on-demand trips, consumers can track the progress of an order, ride, or other service you provide them.
What is journey sharing?
Journey sharing is a feature of Fleet Engine for on-demand rides, used for the Consumer SDK. It provides interfaces that model trip data and follow trip sessions in Fleet Engine, and it provides classes you use to create a rich, map-based display for trip information to your consumer users. You integrate the SDK into your app and set the appropriate role profiles within Fleet Engine to support consumer usage of journey sharing.
Journey sharing provides platform-specific APIs, so you can build journey sharing natively into your applications. The Consumer SDK is available for the following platforms:
Why use journey sharing?
By integrating journey sharing into your on-demand trips applications, you provide a comprehensive vehicle monitoring experience, with near real-time location updates and road-snapped positions. Your consumers can see the vehicle's route overlaid on top of a map, including progress details that help them understand where their ride or delivery is.
What can you do with journey sharing?
You can use information from the Driver SDK and Fleet Engine to create rich mobile SDK views and web service responses that provide the following features:
Provide map UI customizations to fit your branding needs.
The vehicle's current location as it makes its way along the route, with its position updated periodically.
The estimated time of arrival (ETA) for pickup and drop-off locations.
The distance remaining.
Live traffic on the route.
How journey sharing works
At a high level, journey sharing relies on the following mechanisms:
- Appropriate Fleet Engine user roles so that authenticated app users can fetch the trip associated with their order.
- An association between the consumer and the trip, provided by your backend system.
- The Consumer SDK
TripModelandJourneySharingSession, SDK classes that model trip data and share trip sessions in the consumer app.
The Consumer SDK also provides other interfaces and classes so that you can creating a mapping user interface for your app, so that your consumers have a rich app experience complete with details like traffic, map markers, ETA, and route data.
This table shows the flow of a shared journey.
| 1 | Consumer app requests a Trip. | Your backend server gets an on-demand trip request and does the
following:
|
| 2 | Driver accepts the trip | The driver app gets the trip ID and trip information, and the driver accepts the trip. |
| 3 | Consumer app requests access to the journey | The consumer app gets the trip ID from the your backend and requests to start journey sharing. |
| 4 | Driver starts the trip | When the driver uses the driver app to indicate that the trip has started, the app notifies the your backend server through the Driver SDK. For example, when the driver is about to leave the restaurant or drive to the pickup location. |
| 5 | Fleet Engine starts sharing the journey | Fleet Engine starts tracking the journey and sharing its progress with the consumer app. |
| 6 | Consumer app displays the journey | The consumer app notifies the consumer and starts displaying the journey to them, updating the journey as it progresses. |
| 7 | Trip is completed or canceled | When the driver cancels or completes the trip, the driver app disables location tracking, and your backend server tells Fleet Engine to mark the trip as canceled or completed. |
| 8 | Consumer app stops journey sharing | The journey shows as canceled or complete. |
| 9 | The process repeats for the next trip | A new trip is created and the process repeats. |
How to use journey sharing
Select your platform to see how to start sharing journeys.
Android
| 1 | Set up the Consumer SDK in Android | To share journeys for on-demand trips in your app, set up the Consumer SDK. For more information, see Get the Android Consumer SDK. |
| 2 | Set up the journey sharing visual interface | Define a map and add support for vector maps to set up your journey's interface. For more information, see Set up a map. |
| 3 | Share a journey | Follow a trip to share the location of the appropriate vehicle to your consumer. For more information, see Follow a trip. |
| 5 | Update journey progress and handle trip errors | Update details on your trips journey such as travel distance and estimated time of arrival, and handle any errors during said journey. For more information, see Update trip progress and Handle trip errors. |
| 5 | When a journey is complete, stop sharing | Stop following a trip to stop sharing a vehicle's location to your consumer. For more information, see Stop following a trip. |
iOS
| 1 | Set up the Consumer SDK in iOS | To share journeys for on-demand trips in your app, set up the Consumer SDK. For more information, see Get the iOS Consumer SDK. |
| 2 | Set up the journey sharing visual interface | Initialize the map view and handle map events to set up your journey's interface. For more information, see Set up a map. |
| 3 | Share a journey | Follow a trip to share the location of the appropriate vehicle to your consumer. For more information, see Follow a trip. |
| 5 | Update journey progress and handle trip errors | Update details on your trips journey such as travel distance and estimated time of arrival, and handle any errors during said journey. For more information, see Update trip progress and Handle trip errors. |
| 5 | When a journey is complete, stop sharing | Stop following a trip to stop sharing a vehicle's location to your consumer.For more information, see Stop following a trip. |
JavaScript
| 1 | Set up Journey sharing in JavaScript | To share journeys for on-demand trips in your app, set up the Consumer SDK. For more information, see Set up the JavaScript Consumer SDK. |
| 2 | Load and customize the journey sharing map | Enable the Maps JavaScript API and set up authorization to set up your journey's interface. For more information, see Set up a map. |
| 3 | Share a journey | Follow a trip to share the location of the appropriate vehicle to your consumer. For more information, see Follow a trip. |
| 5 | Update journey progress and handle trip errors | Update details on your trips journey such as travel distance and estimated time of arrival, and handle any errors during said journey. For more information, see Update and follow trip progress and Handle trip errors. |
| 5 | When a journey is complete, stop sharing | Stop following a trip to stop sharing a vehicle's location to your consumer. For more information, see Stop journey sharing. |
Components
This section summarizes two necessary components to sharing a journey:
Optionally, you can also customize your journey sharing experience with these components:
Authentication token fetcher
To control access to the location data stored in Fleet Engine, you must do the following:
Implement a JSON Web Token (JWT) creation service for Fleet Engine on your server.
Implement an authentication token fetcher in your web or mobile apps to authenticate access to the location data.
For more information, see the setup guide for Android, iOS, or JavaScript.
Map view and trip trackers
Journey sharing includes components for visualization of vehicles and waypoints, as well as raw data feeds for a driver's ETA or the remaining distance to drive.
The following table describes these components:
| Component | Description |
|---|---|
| Journey sharing map view | The map view manages the lifecycle of a journey, showing waypoints for the location of vehicles as the journey progresses. If the route for a vehicle is known, the map view updates the vehicle route polyline to indicate the progress of the vehicle along its route. |
| Trip location provider in JavaScript | For JavaScript web apps, the trip location provider feeds location
information for tracked objects into the shared journey map. For more
information, see
Instantiate a trip location provider.
You can use the trip location provider to track the following details for a
trip:
|
Tracked location objects
The location provider tracks the location of objects such as waypoints and vehicles, described in the following table.
| Tracked location | Description |
|---|---|
| Pickup location | The pickup location is the location where a journey starts. It marks the pickup location. |
| Destination location | The destination location is the location where a journey ends. It marks the drop off location. |
| Waypoint location | A waypoint location is any intermediate location along the route of a tracked journey. While technically speaking waypoints can include pickup and dropoff locations, waypoints typically refer to intermediate stops along the route. For example, the stops between the pickup and destination locations on a delivery route are waypoint locations. For more information, see Trip waypoints in the Fleet Engine documentation. |
| Vehicle location | The vehicle location is the reported location of a vehicle. For more information, see Vehicle location in the Fleet Engine documentation. |
Style your maps
Marker and polyline styles determine the look and feel of the tracked location objects on the map. You can use custom styling options to change the default styling to match the style of your web application.
Control visibility of tracked locations
The predefined location providers in Fleet Engine follow these visibility rules for tracked location objects on the map. If you create a custom or derived location provider, you may change the visibility rules.
Vehicles are visible only when the trip is in progress: A journey sharing vehicle is visible from the time it is assigned to a trip to the time of drop off. If the trip is canceled, the vehicle is longer visible.
All other location markers are always visible: All other location markers for origin, destination, and waypoints are always shown on the map. For example, a journey sharing drop off location or a shipment delivery location is always shown on the map, regardless of the state of the trip or delivery.
What's next
See the documentation for the platform on which you want to share journeys: