Turn-by-Turn Navigation for Walking and Driving

If you are using Turn-by-Turn Navigation for driving, you have to implement rerouting delegate methods to display actual NMAMapRoute on NMAMapView object. The rerouting is triggered when navigation manager has determined deviation between the route and actual user position. Navigation manager triggers the following methods:

• navigationManager:navigationManagerWillReroute: - when rerouting is triggered.
• navigationManager:didRerouteWithError: - when attempt to reroute finished (it doesn't guarantee that new route was created).
• navigationManager:didUpdateRouteWithResult: - when a change is made to the route being navigated.

The navigationManager:didUpdateRouteWithResult: is the main place for NMAMapRoute redraw. This method might be called in different scenarios:

• User changed route programatically using

  [[NMANavigationManager sharedNavigationManager] setRoute:newRoute];

• After successfully rerouting due to deviation between navigation route and actual user position.
• When navigation is stopped.

The following code is an example of an navigationManager:didUpdateRouteWithResult: implementation:

- (void)navigationManager:(nonnull NMANavigationManager *)navigationManager
 didUpdateRouteWithResult:(nonnull NMARouteResult *)routeResult
{
  if (routeResult && routeResult.routes.count > 0) {
    // Let's add the 1st result onto the map
    self.route = routeResult.routes[0];

    // remove previously created map route from map
    if (self.mapRoute) {
      [self.mapView removeMapObject:self.mapRoute];
    }
    // create new one based on provided route
    if (route) {
      self.mapRoute = [NMAMapRoute mapRouteWithRoute:self.route];
      self.mapRoute.traveledColor = [UIColor clearColor];
      [self.mapView addMapObject:self.mapRoute];
    }
  } else {
    // The routeResult doesn't contain route for redraw.
    // It might occur when navigation stop was called.
  }
}
        

If you are using the Turn-by-Turn Navigation Mode for driving, you can also set HERE SDK to perform guidance (including voice instructions and event callbacks) while the app is in the background. However, there are a few limitations that you should be aware of:

• Unlike the foreground navigation scenario, HERE SDK does not stream map data during background navigation. To support background navigation, HERE requires preloading map data (such as for the current city or state) using NMAMapLoader if your app may be used in the background.
• You cannot render a map (e.g. send it to an external device) when the app is in the background.
• Navigation cannot be started from the background unless this has been previously enabled while the app is in the foreground. Therefore, an app that launches directly to the background cannot reliably launch a navigation session. For more information about this check backgroundNavigationStartEnabled property on the NMANavigationManager class.

You can start navigation using the following methods:

• startTurnByTurnNavigationWithRoute: - Starts the Navigation Manager in Navigation Mode
• startTrackingWithTransportMode: - Starts the Navigation Manager in Tracking Mode

NMANavigationManager setNaturalGuidanceMode: method can be used to enable natural guidance. Natural guidance refers to a type of dynamic information available during navigation where route guidance instructions contain contextual elements around a decision point. These contextual elements may include services, cartographic features, traffic signals. Some examples of natural guidance instructions are:

• "Go past the park on your right, then turn left at Anderson school on Bayview street"
• "Go through the traffic light and turn right before the petrol station"
• "Continue on your route passing the dome building on your right"

NMANavigationManager notifies the client of navigation events through its delegates that implement the NMANavigationManagerDelegate protocol. The delegate protocol includes the following methods:

• navigationManagerDidReachDestination: - Signifies that the destination of navigation was reached
• navigationManager:hasCurrentManeuver:nextManeuver: - Signifies that there is new instruction information available that can be fetched by accessing nextManeuver property in NMANavigationManager
• navigationManager:didUpdateRoute: – Provides the newly calculated NMARoute object which can be used to render a new route on the map
• didUpdateSpeedingStatus:forCurrentSpeed:speedLimit: - Signifies that the user has exceeded the speed limit with the road name and speed limit provided
• navigationManagerDidLosePosition: - Signifies that the system has lost its GPS signal
• navigationManagerDidFindPosition: - Signifies that the system has acquired a GPS signal
• navigationManagerWillReroute: – Signifies that a route recalculation has begun. This is a result of the current position deviating from the original route
• navigationManagerDidReroute: - Signifies that a route recalculation has finished
• navigationManager:didFindAlternateRouteWithResult: - Signifies that the navigation manager has found an improved route
• navigationManager:shouldPlayVoiceFeedbackWithText: - Signifies that a voice feedback is ready to be played. Use this callback return values to retrieve the text to be spoken (if applicable) and to control whether the current voice feedback should be played
• navigationManager:willPlayVoiceFeedbackWithText: - Signifies that a voice feedback event will occur (for example, when a maneuver is being announced)
• navigationManager:didPlayVoiceFeedbackWithText: - Signifies that a voice feedback event has finished
• navigationManager:didFindAlternateRoutes: - Signifies that alternative routes have been found during navigation with traffic avoidance mode enabled

NMASchoolZoneWarnerDelegate provides callback methods to check whether there is school zone ahead, whether user enters or leaves school zone. Callback didDetectSchoolZone occurs when there is school zone ahead if user follows current route direction, it will be triggered in about 100 meters before each NMARoadElement with school zone. Callback didUpdateSchoolZone occurs either when user entered school zone or left. For example:

- (void)schoolZoneWarner:(nonnull NMASchoolZoneWarner *)schoolZoneWarner
   didDetectSchoolZone:(nonnull NMASchoolZoneNotification *)notification
{
  // distance to the road element with school zone
  NSUInteger distance = notification.distance;
  // road element associated with this school zone
  NMARoadElement* roadElement = notification.roadElement;
  // begin time, e.g. Monday 09:00
  NSDate* timeBegin = notification.schoolZoneInfo.timeBegin;
  // end time, e.g. Monday 17:00
  NSDate* timeEnd = notification.schoolZoneInfo.timeEnd;
  float speedLimit = notification.schoolZoneInfo.speedLimit;
}

- (void)schoolZoneWarner:(nonnull NMASchoolZoneWarner *)schoolZoneWarner
   didUpdateSchoolZone:(nonnull NMASchoolZoneInfo *)zoneInfo
{
  if (zoneInfo) {
    // user enters school zone
    float speedLimit = zoneInfo.speedLimit;
  } else {
    // user left school zone
  }
}
        

Developer can also use utility methods from NMASchoolZoneWarnerDelegate to check whether specific road element has school zone. For example:

 // Get road element from geo coordinate
 // Use instance of NMAMapView to get roadElementAtCoordinates
NMARoadElement* roadElement = [NMAMapView roadElementAtCoordinates:coordinate];
 if (roadElement) {
   // Check whether road element has active school zone
   NMASchoolZoneInfo* info = [NMASchoolZoneWarner schoolZoneInfoForRoadElement:roadElement];
   if (info) {
     // provided road element has school zone
   }

   // Check whether school zone is active at specific time
   // GMT: Sunday, 8 March 2020, 00:00:00
   NSDate *sunday = [NSDate dateWithTimeIntervalSince1970:1583625600];
   NMASchoolZoneInfo* infoAtTime = [NMASchoolZoneWarner schoolZoneInfoForRoadElement:roadElement
                                          time:sunday];
   if (infoAtTime) {
     // school zone is active at provided time
   }
 } else {
   // NMARoadElement is nil either because there is no road at the provided location or map
   // data is not loaded. Use NMAMapLoader API to download map area, or use road element from
   // another provider, e.g. from the calculated route.
 }
        

After adding your delegate implementation, your application begins receiving the following method callbacks as the user approaches a highway section that supports Realistic View. The next maneuver callback occurs when a realistic view is available in the second upcoming maneuver (for example, if the next maneuver is to enter a junction), and the current maneuver callback occurs as the most immediate upcoming maneuver is entered (for example, if the user is entering the junction).

• navigationManager:didUpdateRealisticViewsForCurrentManeuver:
• navigationManager:didUpdateRealisticViewsForNextManeuver:

The first two method callbacks mentioned above return an NSDictionary object named realisticViews, which holds one or more NSDictionary of images. To retrieve the NSDictionary of images from realisticViews, use one of the following aspect ratio strings as the key:

• NMARealisticView16x9Key
• NMARealisticView3x5Key
• NMARealisticView4x3Key
• NMARealisticView5x3Key

After performing this step, you can extract the signpost and junction view images from the NSDictionary through NMANavigationManagerSignpostKey and NMANavigationManagerJunctionViewKey keys.

- (void)navigationManager:(NMANavigationManager *)navigationManager
    didUpdateRealisticViewsForCurrentManeuver:(NSDictionary *)realisticViews
{
  NSDictionary *realisticView = [realisticViews objectForKey:NMARealisticView3x5Key];
  NMAImage *junction = [realisticView objectForKey:NMANavigationManagerJunctionViewKey];
  if (junction) {
    //** display the junction image
  }
  NMAImage *signpost = [realisticView objectForKey:NMANavigationManagerSignpostKey];
  if (signpost) {
    //** display the signpost image
  }
}