Navigation Service

The main component responsible for navigation in Navmii SDK is NMNavigationSevice. You can access an instance of this class via NMSdk' navigationService property:

NMNavigationService *navigationService = [NMSdk sharedInstance].navigationService;

Navmii SDK generates various navigation events. To be able to handle these events make one of your classes conform to NMNavigationServiceListener protocol and add an instance of this class to NMNavigationService listeners via addNavigationServiceListener: method:

[[NMSdk sharedInstance].navigationService addNavigationServiceListener:yourListener];

You also can add multiple listeners to NMNavigationService instance. To detach a listener from NMNavigationService instance use removeNavigationServiceListener: method.

These navigation events are:

• change of GPS status
• change of iOS location services authorization status
• change of current position
• update of navigation information (see Navigation Info section)
• change of country of current location
• update of guidance info (see Guidance (v2.0.x))
• passing a waypoint
• reaching the destination
• demo route start
• demo route stop

"Passing a waypoint" and "reaching the destination" events correspond to onWaypointPassed and onArrivalPointReached methods respectively:

- (void)onWaypointPassed {
	NSLog(@"waypoint passed");
}
- (void)onArrivalPointReached {
	NSLog(@"arrival point reached");
}

LOCATION SERVICE AUTHORIZATION

Your app is not allowed to use iOS location service unless you have user's permission. To request user's permission for your app to use location service use one of these methods:

• requestWhenInUseAuthorization

• requestAlwaysAuthorization

[[NMSdk sharedInstance].navigationService requestWhenInUseAuthorization];
//or
[[NMSdk sharedInstance].navigationService requestAlwaysAuthorization];

Calling these methods will trigger a prompt requesting "Always" and "When in use" authorization respectively.

POSITIONING OPTIONS

You can set up the location detection accuracy in meters via locationDetectionAccuracy property. To retrieve user defined CLAuthorizationStatus use locationServicesAuthorizationStatus readonly property. The onLocationServicesAuthorizationChanged: method will be called when this status changes. You can allow or disallow location updates when your app is in background mode via allowsBackgroundLocationUpdates BOOL property. 

//sets location detection accuracy to 20 meters
[[NMSdk sharedInstance].navigationService setLocationDetectionAccuracy:20];
//allows user's location updates in the background mode
[[NMSdk sharedInstance].navigationService setAllowsBackgroundLocationUpdates:YES];

//logs out location services authorization status on change
- (void)onLocationServicesAuthorizationStatusChanged:(CLAuthorizationStatus)status {
	NSLog(@"authorization status - %d", status);
}

When the authorization status is not determined you can prompt the user to allow/disallow location updates throughout requestAlwaysAuthorization and requestWhenInUseAuthorization methods:

[[NMSdk sharedInstance].navigationService requestAlwaysAuthorization];
//or, alternatively
[[NMSdk sharedInstance].navigationService requestWhenInUseAuthorization];

There is also the gpsStatus property indicating if the SDK accepts GPS signal. GPS status is represented as NMGpsStatus enum of the following values:

• NMGpsStatusOK
• NMGpsStatusNoSignal
• NMGpsStatusOff

The onGPSStatusChange: event in NMNavigationServiceListener protocol will bee triggered when the status changes:

- (void)onGpsStatusChange:(NMGpsStatus)status {
	NSLog(@"GPS status has changed to %d", (int)status);
}

RETRIEVING CURRENT POSITION

The user's current position can be retrieved via NMNavigationService's currentPosition readonly property. 

//logs out the user's current position
NMMapCoordinates *currentPosition = [NMSdk sharedInstance].navigationService.currentPosition;
NSLog(@"You are at coordinates: %f lat. %f lon.", currentPosition.latitude, currentPosition.longitude);

The NMNavigationService listeners will be informed on current position change via onCurrentPositionChanged: method:

- (void)onCurrentPositionChanged:(NMMapCoordinates *)coordinate {
	NSLog(@"position changed to coordinates: %f lat. %f lon.", coordinate.latitude, coordinate.longitude);
}

DEMO ROUTE

Navmii SDK allows you to demonstrate the way the real-time traverse of the route will look like on the screen. When the route is calculated, use startDemoRoute and stopDemoRoute methods. Use isDemoRouteActive BOOL property to find out if the demo route is still in progress.

//starts demo route
[[NMSdk sharedInstance].navigationService startDemoRoute];
//stops demo route
[[NMSdk sharedInstance].navigationService stopDemoRoute];

//logs out messages on demo route start and finish
- (void)onDemoRouteStart {
	NSLog(@"demo route started");
}
- (void)onDemoRouteFinish {
	NSLog(@"demo route finished");
}

TRAFFIC ON ROUTE IMAGE

Navmii SDK also creates a bitmap image representing traffic on the current route. To be able to receive this image when it updates, make one of you classes conform to NMTrafficOnRouteImageListener protocol and add an instance of this class to NMNavigationService's "traffic on route image" listeners:

[[NMSdk sharedInstance].navigationService addTrafficOnRouteImage:yourListener];

To detach a "traffic on route image" listener use removeTrafficOnRouteImageListener: method.

- (void)onTrafficOnRouteImageUpdated:(UIImage *)image {
	//handle the image here
}