Page Comparison

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.

CREATING ROUTE NAVIGATOR

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.

USING ROUTE NAVIGATOR

Route navigator has different responsibilities all related to each other:

• route navigator performs navigation along the specified route. Route navigator gets GPS position updates internally, updates the route navigation state and notifies if any changes occur.
• route navigator is able to handle rerouting. This option is intended to ease handling the rerouting process for SDK user. If rerouting handling is enabled, navigator, once rerouting is required, notifies that rerouting has started, calculates a new route, starts navigating along the new route and notifies that new route navigation has started.
• route navigator is able to handle rerouting by traffic. This option is intended to ease handing the rerouting by traffic process for SDK user. If rerouting by traffic is enabled, navigator, once traffic has been updated, applies it to the current route, if possible, or builds a new route otherwise, builds alternative routes if possible, and notifies that new route navigation has started, traffic was updated and alternative routes are available.
• route navigator is able to visualize changes in route by emitting route visualizer requests. To achieve such a behaviour you need to connect the route visualizer (routeVisualizer property of NMSdk) to route navigator using addRouteVisualizerRequestListener: method of NMRouteNavigator.

ROUTE NAVIGATION

Route navigation starts by calling the startNavigatingTheRoute: method. The route parameter is an an instance of NMRoute class instance which represents the a route to navigate. The source of routes is Routing Service. After the route navigation was 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. Notifications about Callbacks for the following events are available:

• the 'on-route state' changes: user has got off the route or got back on the route. The SDK user may need this information to handle rerouting manually;
• position on route (distance or time to destination) changes;
• the next direction information or distance to it the next direction changes;
• a waypoint has been passed or destination has been reached.

...

Route navigator also provides the route navigation guidance which whose callbacks can be gotten by conforming to NMGuidanceListener protocol.

User is able to stop the route navigation by calling the stopNavigation method.

AUTOMATIC REROUTING HANDLING

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 user is the GPS position has got off the route being navigated, calculates a new route and applies it. User gets notifications Callbacks about the automatic rerouting handling process can be gotten by conforming to NMReroutingListener protocol. The protocol has the onReroutingStarted method, which is called once automatic rerouting handling process starts, and the onReroutingFinished: method, which is called once the process finishes. The onReroutingFinished: method has the newRoute parameter, which is the a new instance of NMRoute class instance representing the new route being navigated. The newRoute can be nil if rerouting handling is no longer required (i.e. user GPS position has returned back to the previous route).

Rerouting The rerouting engine has an algorithm, which attempts tries to use a route the route most similar to the one user initially started to navigate by calling the passed to the startNavigatingTheRoute: method. NMRouteNavigator has the reroutingSettingswhich property, which allows user to tune the algorithm a bit.

AUTOMATIC REROUTING BY TRAFFIC HANDLING

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, the route navigator internally get gets notifications from the traffic service that traffic near the current position was has been updated, and, once it happens, handles rerouting by traffic. User The SDK user gets notifications callbacks about the rerouting by traffic handling process by conforming to NMReroutingByTrafficListener protocol. The protocol has the a single method, which is called once the rerouting by traffic occurred. Here it is the method declaration:

- (void)onReroutingByTrafficOccurredWithOldTimeToDestination:(NSInteger)oldTimeToDestinationInSeconds
                                        newTimeToDestination:(NSInteger)newTimeToDestinationInSeconds
                                                    newRoute:(nullable NMRoute *)newRoute
                                          resemblingOldRoute:(BOOL)doesNewRouteResembleOldOne
                                           alternativeRoutes:(nullable NSArray<NMRoute *> *)alternativeRoutes;

Rerouting The rerouting by traffic engine may change create a new instance of NMRoute class instance used for navigation during rerouting by traffic handling. newRoute . The newRoute parameter will have non-null value if that happens. The doesNewRouteResembleOldOne parameter indicates whether the route, being navigated after the rerouting by traffic occurred, is identical (takes the same roads) to the route being navigated before thatrerouting. So , even if the newRoute is non-null nil but the doesNewRouteResembleOldOne is YES, what  means that means is the route being navigated hasn't changed (takes the same roads).

The alternativeRoutes is the parameter is a list of alternative routes with the latest traffic applied, which can be used by user for navigation. To use Use startNavigatingTheRoute: method to start navigation along one of the alternative routes for navigation user need to call startNavigatingTheRoute: method..

GUIDANCE

Navmii SDK allows you to setup the way the navigation guidance will be provided. It's possible throughout the NMRouteNavigator's instance property guidanceSettings. You can set the guidance output either to text or switch it off. If you pass NMGuidanceOutputText to the NMGuidanceSettings's property guidanceOutput, you'll be able to receive NSString instances with navigation guidance in NMNavigationListener - (void)onGuidanceTextReady:(NSString *)guidanceText method.

- (void)onGuidanceTextReady:(NSString *)guidanceText {

   NSLog(guidanceText);

}

You can also set guidance language via the NMGuidanceSettings's locale property. To get the list of all languages supported by the SDK use the supportedLocales property.

// Sets guidance language to American English
NMGuidanceSettings *settings = navigator.guidanceSettings;
settings.locale = @"en-US";

Currently supported languages:

• Czech

• Danish

• English (UK)

• English (US)

• Finnish

• French (France)

• German

• Italian

• Korean

• Norwegian

• Polish

• Portugese (Brazil)

• Portugese (Portugal)

• Russian

• Spanish (Spain)

• Swedish

• Turkish

Voice guidance

It's also possible to receive voice guidance instructions. To do this, first set the path to the directory containing the voice packs by using the NMConfigurationSettings property voicePacksPath. After initialising the SDK, you can retrieve the list of available voice packs with the NMGuidanceSettings availableVoicePacks property, and select one using NMGuidanceSettings voicePack. By passing NMGuidanceOutputVoice to the NMGuidanceSettings guidanceOutput property, directions will be announced using the chosen voice pack.

Example:

- (void)configureSDK {

	//Setup Voice Resources here.

 	NMConfigurationSettings *configurationSettings = [NMConfigurationSettings new];
	configurationSettings.voicePacksPath = [[NSBundle mainBundle] URLForResource:@"VoicePacksFolder" withExtension:nil].path;
}

- (void)setVoiceGuidance {
	
	//Request available voice packs and pass selected one to settings.
	
	NMRouteNavigator *navigator = navmiiSDK.routeNavigator;
	NMGuidanceSettings *guidanceSettings = navigator.guidanceSettings;

	NSArray<NMVoicePack *> *voicePacks = guidanceSettings.availableVoicePacks;
    
	if ([voicePacks count] > 0) {
		NMVoicePack *voicePack = ...// select voice pack here
        guidanceSettings.voicePack = voicePacks;
        guidanceSettings.guidanceOutput = NMGuidanceOutputVoice;
    }
}