RouteTracker

class RouteTracker : Resourceable

Uses a location to provide status and progress updates as a route is traversed (by a moving vehicle, for example). RouteTracker can give the time or distance to the next maneuver, notify if the location is off-route, and regenerate a new route if necessary. Basic workflow:

  1. Create a new RouteTracker instance.

  2. Enable rerouting with RouteTracker.enableRerouting(ReroutingParameters) (if supported by the underlying route service).

  3. Use RouteTracker.trackLocation(Location) to track the location of the device.

  4. Subscribe to RouteTracker.trackingStatusChanged to get the TrackingStatus as the location changes.

  5. Subscribe to RouteTracker.newVoiceGuidance to get the VoiceGuidance whenever new instructions are available.

  6. If there are multiple stops, call RouteTracker.switchToNextDestination() each time DestinationStatus.Reached status is returned. Before calling RouteTracker.switchToNextDestination() make sure that TrackingStatus.remainingDestinationCount 1, a value of 1 means the last destination is being approached.

Since

200.1.0

Constructors

Link copied to clipboard
constructor(routeResult: RouteResult, routeIndex: Int, skipCoincidentStops: Boolean)

Creates a Route Tracker using a specific route from a route result with an option to specify treating coincident stops as a single destination. An exception is thrown if the Route is not found or if it lacks Route.stops and Route.directionManeuvers.

Properties

Link copied to clipboard

Reports if routes are automatically regenerated when tracking status is off-route. True if rerouting is enabled, otherwise False.

Link copied to clipboard

Sets new voice guidance callback.

Link copied to clipboard

Sets reroute completed callback.

Link copied to clipboard
val rerouteStarted: SharedFlow<Unit>

Sets reroute started callback.

Link copied to clipboard

Indicates if multiple stops in a row at the same location should treated as one stop. When true, if there are multiple stops, in a row, at the same network location the new voice guidance event will fire a single time and calling RouteTracker.switchToNextDestination() will skip over the other coincident stops, setting the state to the next relevant direction maneuver. If the value is false each stop will be treated as a unique destination. The default value for this property is true. If your route does not have coincident stops the value of this property will have no effect.

Link copied to clipboard

Status for the current location on the route.

Link copied to clipboard

The unit system used in voice guidance commands. Default value is UnitSystem.Metric. Supported values are UnitSystem.Metric and UnitSystem.Imperial.

Functions

Link copied to clipboard

Cancels a running reroute task. If rerouting is in progress, this method will interrupt the background route task process.

Link copied to clipboard

Disables automatic rerouting. When disabled, the tracker will not automatically recalculate a route when the tracking status is off-route.

Link copied to clipboard
suspend fun enableRerouting(parameters: ReroutingParameters): Result<Unit>

Enables automatic rerouting when the tracker detects an off-route status. Re-routing only occurs when the current location is off-route, but on or near the transportation network edges. For example if an off-route state is detected but the tracked location is in a parking lot, away from any transportation network edges, re-routing will not occur, and will occur only once a subsequent tracked location is on or near the transportation network edges.

Link copied to clipboard

Gets the current VoiceGuidance object. The most recent voice guidance based on the last Location used by RouteTracker.trackLocation(Location). It can be used to repeat last/latest voice guidance.

Link copied to clipboard
fun setSpeechEngineReadyCallback(speechEngineReady: () -> Boolean)

Sets a callback which returns the speech engine ready status. Set the speech engine activity status using this lambda to avoid speech event conflicts. This logic is used by RouteTracker before new RouteTracker.newVoiceGuidance is raised to check if the speech engine is busy. If it is busy it will postpone raising the voice guidance event until next RouteTracker.trackLocation will be called. Here is an example of how it can be used with a text-to-speech engine:

Link copied to clipboard

Starts tracking progress to the next destination in the Route. Use RouteTracker.switchToNextDestination() when the tracker reports a DestinationStatus.Reached status. Before calling RouteTracker.switchToNextDestination() make sure that TrackingStatus.remainingDestinationCount 1 (a value of 1 means navigation is proceeding to last destination). This method can also be called after DestinationStatus.Approaching is raised in cases where the location cannot get near enough to the destination point for DestinationStatus.Reached to be raised (such as the center of a park or shopping center, for example). RouteTracker.trackLocation(Location) needs to be called at least once before calling this method otherwise an error will be thrown. RouteTracker.trackLocation(Location) is needed for getting TrackingStatus and for handling visitFirstStopOnStart.

Link copied to clipboard
suspend fun trackLocation(location: Location): Result<Unit>

Provides route tracking status relative to the provided location. The location generally comes from a GPS but may also be a simulated or manually entered location. It must have valid values for X and Y coordinates, speed (in meters per second), course (in degrees), and a timestamp. Events fired for RouteTracker when completed.