Guidance

Guidance contains information on the current guidance session and lets you follow events in guidance mode. Use the Navigation.getGuidance method to get it.

Track locationTrack location

By default, Navigation is created in suspended mode, where location isn't tracked and guidance is off. To start tracking the current device location, use resumed mode. That keeps the user's location up to date.

To manage the location tracking mode, use the Navigation.resume and Navigation.suspend methods.

Start/stop guidanceStart/stop guidance

To start route guidance, use the Navigation.startGuidance method. It takes the route as its only argument.

To stop guidance, use the matching Navigation.stopGuidance method.

Guidance dataGuidance data

Let's look at the main data Guidance provides access to.

• Current route: Guidance.getCurrentRoute contains the route where guidance is currently active or the null value if guidance is inactive. In guidance mode, the current route can change, for example, if the user deviates from the route or chooses an alternate route.

• User location: Guidance.getLocation contains the current user location. That includes the location coordinates, current direction, location precision, guidance speed, and more.

• Speeding: Guidance.getSpeedLimit and Guidance.getSpeedLimitStatus provide information on the speed limit for the current route section. Guidance.getSpeedLimitsPolicy provides information about speed limits for different areas in the current region (in the city, outside the city, and on highways).

The complete API is available in the Guidance documentation.

WindshieldWindshield

The Windshield entity is used to provide information about oncoming maneuvers on the route, road markings and events, speed limits, and road signs.

To access the Windshield instance, use the Guidance.getWindshield method.

The Windshield entity status is defined by the following data:

• Maneuvers: Using Guidance.getManoeuvres, you can get a list of maneuvers on the route. Each maneuver is described by its position on the route, location, and the Annotation instance that contains information about its type.

• Road markings: Guidance.getLaneSigns returns a list where each instance contains information about the lane the user must be on. It is characterized by its position on the route and the LaneSign instance, which defines the road markings type at a road section. The LaneSign instance contains the list of Lane with information about each separate traffic lane, its direction, type, and possible maneuvers.

• Road events: Using Guidance.getRoadEvents, you can get a list of road events on the route as well as information about speed limits.

• Road signs: The Guidance.getDirectionSigns method returns a list of road signs on the route. For example, a sign that indicates the next route section includes a tunnel or a highway

Using WindshieldListener, you can follow Windshield status change events.

You can see an example of how Windshield can be used for implementing the UI component that displays information about the next maneuver and lane markings in the demo app.

EventsEvents

In guidance mode, the guidance status changes constantly. Use the GuidanceListener interface to follow guidance events.

val guidanceListener = object : GuidanceListener {
    override fun onLocationChanged() = Unit
    override fun onCurrentRouteChanged(reason: RouteChangeReason) = Unit
    override fun onRouteLost() = Unit
    override fun onReturnedToRoute() = Unit
    override fun onRouteFinished() = Unit
    override fun onWayPointReached() = Unit
    override fun onStandingStatusChanged() = Unit
    override fun onRoadNameChanged() = Unit
    override fun onSpeedLimitUpdated() = Unit
    override fun onSpeedLimitStatusUpdated() = Unit
    override fun onAlternativesChanged() = Unit
    override fun onFastestAlternativeChanged() = Unit
}
guidance.addListener(guidanceListener)

GuidanceListener lets you follow navigation events (deviation from the route, return to the route, and arrival at intermediate and final stops) and guidance status changes (for the current user location, street name, speed limit information, list of alternatives, and more).

Guidance alternativesGuidance alternatives

Local alternatives are the alternate routes available in guidance mode. They're recalculated automatically. To follow this event, use the GuidanceListener.onAlternativesChanged method.

To switch from the current route to an alternate one, use the Guidance.switchToRoute method.

Faster alternative routesFaster alternative routes

Route guidance sessions might sometimes last as long as several hours. In these cases, the initially built route might become outdated and less convenient with time. This is relevant for city guidance since the traffic situation might change quite often. NaviKit SDK solves this problem and provides an opportunity to get a faster alternative route.

The Guidance.getFastestAlternative method returns information about a faster alternative route, if one exists. Start guidance along such a route to change the current route to a faster one.

Using the GuidanceListener.onFastestAlternativeChanged handler method, you can follow notifications about changes in the faster route.

AnnotationsAnnotations

To set up voice guidance (voice annotations) for the route, use the Annotator class.

To enable and disable annotations, use the Annotator.mute and Annotator.unmute methods.

For the annotator to start working, add a Speaker delegate to it and implement it yourself.

To change the annotation language, use the Navigation.setAnnotationLanguage method.

Annotations are divided into two types: AnnotatedRoadEvents are related to road events and AnnotatedEvents are related to route warnings. You can manage the amount of activity for specific annotations using the Annotator.setAnnotatedRoadEvents and Annotator.setAnnotatedEvents methods.

You can follow Annotator class events using the AnnotatorListener interface. It notifies you about annotator actions (the type of event that was performed).

Restore statusRestore status

You can restore the guidance status by serializing/deserializing Navigation.

1. To do so, serialize Navigation using the NavigationSerialization.serialize method.

   val serializedNavigation = NavigationSerialization().serialize(navigation)
   

2. serializedNavigation now contains a navigation copy. You can save it to a disk and later restore it using deserialization.

3. Using NavigationSerialization.deserialize, create a new navigation instance.

   val navigation = NavigationSerialization().deserialize(serializedNavigation)
   

Before closing the app, you can save Navigation to a disk and restore it when you open the app again later. Because guidance status is in Guidance and guidance is part of Navigation, it'll also be restored, and the last guidance session will continue.

There's an example of how to implement the logic for restoring guidance statuses in the demo app.

Guidance simulationGuidance simulation

When developing and testing navigation apps, you may need to check how the guidance scenario works. To do so, use third-party tools for simulating user locations or the ready-made simulation API in NaviKit SDK.

To enable location simulation along a route or in an arbitrary direction, use the LocationSimulator class.

Here's an example of how to implement the guidance simulation manager:

class SimulationManager {

    private var locationSimulator: LocationSimulator? = null

    private val locationSimulatorListener: LocationSimulatorListener {
        resetSimulation()
    }

    fun startSimulation(route: DrivingRoute) {
        locationSimulator = MapKitFactory.getInstance().createLocationSimulator(route.geometry)
        locationSimulator?.apply {
            subscribeForSimulatorEvents(locationSimulatorListener)
            speed = 20.0
            MapKitFactory.getInstance().setLocationManager(this)
            startSimulation(SimulationAccuracy.COARSE)
        }
    }

    fun resetSimulation() {
        locationSimulator?.unsubscribeFromSimulatorEvents()
        locationSimulator = null
        MapKitFactory.getInstance().resetLocationManagerToDefault()
    }

    fun setSpeed(value: Double) {
        locationSimulator?.speed = value
    }
}

The startSimulation method accepts the route for guidance simulation. When you use MapKit.createLocationSimulator, a new LocationSimulator is created. You need to configure it:

1. Follow the simulation finish event using LocationSimulatorListener.
2. Set the movement speed value.
3. Change the LocationManager implementation to the newly created locationSimulator.
4. Start the simulation.

The simulation is reset in resetSimulation. With MapKit.resetLocationManagerToDefault, the location simulation manager changes to the default option, which reads the user's current location.

There's a detailed example of route simulation in the demo app.

Background guidanceBackground guidance

Background guidance refers to a guidance session that can continue even after the app's Activity is hidden or killed.

After the app's Activity loses focus, the Android system may kill it to free up resources. The app could then be closed at any time. For the Android app to work even when Activity dies, use the foreground service, which is one of the main components of Android apps.

To implement background guidance, start the foreground service in guidance mode. It'll display a notification. After Activity is closed, Navigation must stay in resumed mode. That way, the app won't be killed by the Android system, and voice guidance will work in background mode.