HERE iOS SDK Developer's Guide

Venue Navigation

This section gives an overview of the classes and interfaces associated with 3D Venues navigation features.

Important: Venue Navigation is currently offered as a beta feature. APIs may change without notice.

Natural Guidance for Venue Maneuvers

Venue maneuvers provide the names of the closest POIs for natural guidance purposes. For each maneuver, this is the closest POI within a natural guidance radius around the position of the maneuver. If no POI exists within this radius, an empty string is returned. The natural guidance radius is a global parameter common to all maneuvers that may be set and queried by the user.

Note: For more information about natural guidance, see Turn-by-Turn Navigation for Walking and Driving.
//Set the max distance a POI may have to a maneuver to be considered for natural guidance to 10 meters
NMAVenue3dRouteManeuver.naturalGuidanceRadius = 10.0;
//Get the natural guidance POI of a maneuver
float naturalGuidanceRadius = NMAVenue3dRouteManeuver.naturalGuidanceRadius;
//If there is no suitable POI in the specified radius around the maneuver,
//the returned string will be empty.
NSString *naturalGuidance = myManeuver.naturalGuidancePOI;

Indoor Navigation

Your app can use the venue navigation manager to receive indoor navigation events.

The venue navigation manager is obtained by a call to NMAVenue3dMapLayer.venueNavigationManager. From this point on, let's assume that the variable venueNavigationManager points to the venue navigation manager.

The following is an example of how to listen for indoor navigation events:

#import "NMAVenue3dCombinedRoute.h"
#import "NMAVenue3dNavigationManager.h"
#import "NMAVenue3dRouteManeuver.h"
#import "NMAVenue3dVenueRouteSection.h"

@interface VenueNavigationExample<NMAVenue3dNavigationListener>

/**
 * Called when the destination of turn-by-turn navigation is reached.
 *
 * When the destination is reached, NMAVenue3dNavigationManager -stop is automatically
 * called. When this callback is received, the navigation manager state will be
 * NMAVenue3dNavigationStateIdle.
 *
 */
- (void)navigationManagerDidReachDestination:(nonnull NMAVenue3dNavigationManager *)navigationManager;

/**
 * Called when the current (upcoming) maneuver is updated.
 *
 * \param navigationManager The NMAVenue3dNavigationManager object.
 * \param maneuver The current (upcoming) maneuver to be made.
 * \param nextManeuver The maneuver to be made AFTER THE CURRENT MANEUVER.
 *
 * \note The "current" maneuver is the upcoming, or next, maneuver to be taken. The "next"
 * maneuver is actually the maneuver to be taken after the current maneuver.
 */
- (void)navigationManager:(nonnull NMAVenue3dNavigationManager *)navigationManager
     hasCurrentManeuver:(nullable NMAVenue3dRouteManeuver *)maneuver
       nextManeuver:(nullable NMAVenue3dRouteManeuver *)nextManeuver;

/**
 * Called when the navigation manager loses its indoor position.
 *
 * \param navigationManager The NMAVenue3dNavigationManager object.
 */
- (void)navigationManagerDidLosePosition:(nonnull NMAVenue3dNavigationManager *)navigationManager;

/**
 * Called when the navigation manager finds its indoor position.
 *
 * \param navigationManager The NMAVenue3dNavigationManager object.
 */
- (void)navigationManagerDidFindPosition:(nonnull NMAVenue3dNavigationManager *)navigationManager;

/**
 * Called when a change is made to the route section being navigated.
 *
 * This can occur after successful rerouting due to the user leaving the current route (see
 * navigationManager:navigationManagerWillReroute).
 *
 * \param navigationManager The NMAVenue3dNavigationManager object.
 * \param routeSection NMAVenue3dVenueRouteSection representing the route section that was set.
 * \param combinedRoute NMAVenue3dCombinedRoute representing the current route.
 */
- (void)navigationManager:(nonnull NMAVenue3dNavigationManager *)navigationManager
  didUpdateRouteSection:(nonnull NMAVenue3dVenueRouteSection *)routeSection
      inCombinedRoute:(nonnull NMAVenue3dCombinedRoute *)combinedRoute;

/**
 * Called when rerouting is triggered due to the user leaving the current route section.
 *
 * If a new route section is successfully calculated, it is immediately applied to
 * the current navigation session and navigationManager:didUpdateRouteSection: is called.
 * After rerouting, the navigationManager:didUpdateRouteSection: is called.
 *
 * \param navigationManager The NMAVenue3dNavigationManager object.
 */
- (void)navigationManagerWillReroute:(nonnull NMAVenue3dNavigationManager *)navigationManager;

/**
 * Called when rerouting, due to the user leaving the current route section, has finished.
 *
 * This method just means an attempt to reroute finished and does not guarantee that
 * a new route was successfully created.
 *
 * \param navigationManager The NMAVenue3dNavigationManager object.
 */
- (void)navigationManagerDidReroute:(nonnull NMAVenue3dNavigationManager *)navigationManager;

@end

- (void)navigationManager:(nonnull NMAVenue3dNavigationManager *)navigationManager
     hasCurrentManeuver:(nullable NMAVenue3dRouteManeuver *)maneuver
       nextManeuver:(nullable NMAVenue3dRouteManeuver *)nextManeuver
{
  NSString *guidance = maneuver.naturalGuidancePOI;
  if ([guidance length] == 0) {
    NSLog(@"maneuver without natural guidance");
  } else {
    NSLog(@"maneuver natural guidance: %@", guidance);
  }
}

This class can be registered with the venue navigation manager by invoking [venueNavigationManager addListener:[[VenueNavigationExample alloc] init]].

Combined Indoor and Outdoor Navigation

Your app can register with the combined navigation manager to receive combined navigation events. Combined navigation events are used when a route contains at least one indoor and one outdoor segment.

For example, the venue navigation manager is obtained by a call to NMAVenue3dMapLayer.combinedNavigation. From this point on, let's assume that the variable combinedNavigationManager points to the venue navigation manager.

The following is an example of how to listen for combined navigation events:

#import "NMAVenue3dCombinedNavigation.h"
#import "NMAVenue3dCombinedRoute.h"
#import "NMAVenue3dLinkRouteSection.h"
#import "NMAVenue3dMapLayer.h"
#import "NMAVenue3dOutdoorRouteSection.h"
#import "NMAVenue3dVenueRouteSection.h"

@interface CombinedNavigationExample<NMAVenue3dCombinedNavigationListener>

@property NMAVenue3dMapLayer *venueLayer;

/**
 * Called when the destination of turn-by-turn navigation is reached.
 *
 * When the destination is reached, NMAVenue3dCombinedNavigation -stop is automatically
 * called.
 */
- (void)navigationManagerDidReachDestination:(nonnull NMAVenue3dCombinedNavigation *)navigationManager

/**
 * Called when a change is made to the combined route being navigated.
 *
 * This can occur after successful rerouting due to the user leaving the current route (see
 * navigationManager:navigationManagerWillReroute).
 *
 * \param navigationManager The NMAVenue3dCombinedNavigation object.
 * \param combinedRoute NMAVenue3dCombinedRoute representing the current route.
 */
- (void)navigationManager:(nonnull NMAVenue3dCombinedNavigation *)navigationManager
   didUpdateCombinedRoute:(nonnull NMAVenue3dCombinedRoute *)combinedRoute;

/**
 * Called when an indoor section of the combined route will be started.
 *
 * \param navigationManager The NMAVenue3dCombinedNavigation object.
 * \param indoorSection NMAVenue3dVenueRouteSection representing the next indoor section.
 * \param combinedRoute NMAVenue3dCombinedRoute representing the current route.
 */
- (void)navigationManager:(nonnull NMAVenue3dCombinedNavigation *)navigationManager
   willStartIndoorSection:(nonnull NMAVenue3dVenueRouteSection *)indoorSection
      inCombinedRoute:(nonnull NMAVenue3dCombinedRoute *)combinedRoute;

/**
 * Called when an link section of the combined route will be started.
 *
 * \param navigationManager The NMAVenue3dCombinedNavigation object.
 * \param linkingSection NMAVenue3dLinkRouteSection representing the next link section.
 * \param combinedRoute NMAVenue3dCombinedRoute representing the current route.
 */
- (void)navigationManager:(nonnull NMAVenue3dCombinedNavigation *)navigationManager
  willStartLinkingSection:(nonnull NMAVenue3dLinkRouteSection *)linkingSection
      inCombinedRoute:(nonnull NMAVenue3dCombinedRoute *)combinedRoute;

/**
 * Called when an outdoor section of the combined route will be started.
 *
 * \param navigationManager The NMAVenue3dCombinedNavigation object.
 * \param outdoorSection NMAVenue3dOutdoorRouteSection representing the next outdoor section.
 * \param combinedRoute NMAVenue3dCombinedRoute representing the current route.
 */
- (void)navigationManager:(nonnull NMAVenue3dCombinedNavigation *)navigationManager
  willStartOutdoorSection:(nonnull NMAVenue3dOutdoorRouteSection *)outdoorSection
      inCombinedRoute:(nonnull NMAVenue3dCombinedRoute *)combinedRoute;

@end

- (void)navigationManager:(nonnull NMAVenue3dCombinedNavigation *)navigationManager
   didUpdateCombinedRoute:(nonnull NMAVenue3dCombinedRoute *)combinedRoute
{
  // Show route.
  NMAVenue3dRoutingController* routingController = venueLayer.venueRoutingController;
  [routingController showRoute:combinedRoute];
}

This class can be registered with the combined navigation manager by invoking [combinedNavigationManager addListener:[[CombinedNavigationExample alloc] init]].

Audio and Haptic Feedback

It is possible to enable audio feedback (beeps) and haptic feedback (vibrations) for specific navigation events such as maneuver change, rerouting, and reaching destinations.

To enable audio feedback on maneuver events, invoke venueNavigationManager.beepsEnabled = YES.

To enable haptic feedback on maneuver events, invoke venueNavigationManager.vibrationEnabled = YES.

See the API documentation of NMAVenueNavigationManager for methods to query the current status of the audio and haptic feedback settings.

Maneuver Zoom

It is possible to enable automatically zooming in to a certain zoom level in the vicinity of a maneuver. This zooming in will only occur if the current zoom level is less that the zoom level specified for maneuver zoom. For example, if the maneuver zoom level has been set to 19, but the user is already viewing the map at a zoom level of 20, no zooming in (or out) will occur.

You can enable maneuver zoom by invoking venueNavigationManager.maneuverZoomEnabled = YES.

Set the distance from a maneuver at which maneuver zoom will be activated to five meters by invoking venueNavigationManager.maneuverZoomDistance = 5.0.

Set the zoom level to which maneuver zoom will zoom in in the vicinity of a maneuver to 20 by invoking venueNavigationManager.maneuverZoomLevel = 20.

See the API documentation of NMAVenue3dNavigationManager for methods to query the current status of the maneuver zoom settings.