The core component of Navmii SDK responsible for route navigation is NMRouteNavigator. This class provides the API to control the route navigation process, to get navigation information and guidance updates. The class is also able to handle the rerouting and the rerouting by traffic.
NMSdk class contains the routeNavigator
property providing access to the instance of NMRouteNavigator. The route navigator instance can be accessed only after the SDK was started.
Route navigator has different responsibilities all related to each other:
routeVisualizer
property of NMSdk) to route navigator using addRouteVisualizerRequestListener:
method of NMRouteNavigator.Route navigation starts by calling the startNavigatingTheRoute:
method. The route
parameter is an instance of NMRoute class which represents a route to navigate. The source of routes is Routing Service. After the route navigation has started, the route navigator gets GPS position updates internally, updates the route navigation state and notifies if any changes occur. Those "notifications" can be gotten by conforming to NMRouteNavigationListener protocol. Callbacks for the following events are available:
Route navigator has properties to access the latest route navigation information at any time.
Route navigator also provides the route navigation guidance whose callbacks can be gotten by conforming to NMGuidanceListener protocol.
User is able to stop the route navigation by calling the stopNavigation
method.
As mentioned above NMRouteNavigator is able to handle rerouting automatically. The feature is enabled by default, but NMRouteNavigator class has the reroutingEnabled
property which can be used to disable or enable the feature. If automatic rerouting handling is enabled, the route navigator tracks the on-route state and, once vehicle has got off the route, calculates a new route and applies it. The SDK user can get callbacks about the automatic rerouting by conforming to NMReroutingListener protocol. The protocol has the onReroutingStarted
method, which is called once automatic rerouting starts, and the onReroutingFinished:
method which is called once the process finishes. The onReroutingFinished:
method has the newRoute
parameter, which is a new instance of NMRoute class representing new route being navigated. The newRoute
can be nil
if rerouting handling is no longer required (i.e. user has returned back to the previous route).
The rerouting engine has an algorithm which attempts to use a route similar to the one passed to the startNavigatingTheRoute
: method. NMRouteNavigator has the reroutingSettings
property, which allows to tune the algorithm a bit.
As mentioned above NMRouteNavigator is able to handle rerouting by traffic automatically. The feature is enabled by default, but NMRouteNavigator class has the reroutingByTrafficEnabled
property which can be used to disable or enable the feature. If automatic rerouting by traffic handling is enabled, route navigator internally get notifications from traffic service that traffic near current position was updated, and, once it happens, handles rerouting by traffic. User gets notifications about rerouting by traffic handling by conforming to NMReroutingByTrafficListener protocol. The protocol has the single method which is called once rerouting by traffic occurred. Here it is:
- (void)onReroutingByTrafficOccurredWithOldTimeToDestination:(NSInteger)oldTimeToDestinationInSeconds newTimeToDestination:(NSInteger)newTimeToDestinationInSeconds newRoute:(nullable NMRoute *)newRoute resemblingOldRoute:(BOOL)doesNewRouteResembleOldOne alternativeRoutes:(nullable NSArray<NMRoute *> *)alternativeRoutes; |
Rerouting by traffic engine may change NMRoute class instance used for navigation during rerouting by traffic handling. newRoute
will have non-null value if that happens. doesNewRouteResembleOldOne
parameter indicates whether route being navigated after rerouting by traffic occurred is identical (takes the same roads) to the route being navigated before that. So, even if newRoute
is non-null but doesNewRouteResembleOldOne
is YES
, what that means is route being navigated hasn't changed (takes the same roads).
alternativeRoutes
is the list of alternative routes with the latest traffic applied which can be used by user for navigation. To use one of alternative routes for navigation user need to call startNavigatingTheRoute:
method.