HERE iOS SDK Developer's Guide

Turn-by-Turn Navigation for Walking and Driving

Note: [Important] Application developers using the Turn-by-turn Guidance APIs are required to thoroughly test their applications in all expected usage scenarios to ensure safe and correct behavior. Application developers are responsible for warning their users of the following obligations:
  1. Do not follow instructions that may lead to an unsafe or illegal situation
  2. Obey all local laws.
  3. Be aware that using a mobile phone or some of its features while driving may be prohibited.
  4. Always keep hands free to operate the vehicle while driving.
  5. The first priority while driving should be road safety.

The HERE iOS SDK supports navigation on pedestrian, car, and truck routes. Using this feature, your app can check the current device position against a calculated route and provide just-in-time navigational instructions, both as visual and voice instructions. Two navigation modes are supported for walking and driving: Turn-by-Turn Navigation Mode, which takes the calculated route and matches the current position against the route, and Tracking Mode, which only tracks the current position without using a route. In Tracking Mode, no voice instructions are provided. For more information on voice instructions, please see Voice Instructions.

Note: Your application should switch to the navigation-specific map schemes while performing car or pedestrian navigation. For more information on using these schemes, see Map Schemes.
Figure 1. Turn-by-Turn Navigation with Speed Warning

Enabling Background Navigation

If you are using the Turn-by-Turn Navigation Mode for driving, you can also set the HERE SDK to perform guidance (including voice instructions and event callbacks) while the app is in the background. To enable this feature, please perform the following steps:

  1. In Xcode's Capabilities tab, enable Background Modes and check the following entries:
    • Audio and AirPlay
    • Location updates
    Figure 2. Background Modes option in Xcode
  2. Next, turn on background navigation in NMANavigationManager:
    [NMANavigationManager sharedNavigationManager].backgroundNavigationEnabled = YES;

The NMANavigationManager Class

The NMANavigationManager class is responsible for providing voice and visual instructions to the user while driving or walking. The Navigation Manager is a singleton class, and the singleton instance can be accessed using [NMANavigationManager sharedNavigationManager].

You can start navigation using the following methods:
  • startTurnByTurnNavigationWithRoute: - Starts the Navigation Manager in Navigation Mode
  • startTrackingWithTransportMode: - Starts the Navigation Manager in Tracking Mode
Note:
  • Navigation operations require device positioning. When navigation is started in the Navigation Manager, the NMAPositioningManager is also started automatically. By using NMAPositioningManager with a position data log, the HERE SDK can perform a simulated navigation session. For more details on using simulated position data, consult Basic Positioning.
  • The HERE SDK may not start voice guidance immediately if the user is far from a road when Turn-by-Turn Navigation Mode begins. Your application should display a message such as "head to the nearest road" until voice guidance begins.

NMANavigationManager also provides relevant information that your application can display during a navigation session, such as distances, upcoming maneuvers, and average travel speed. Upcoming maneuvers are represented by the currentManeuver and nextManeuver properties. currentManeuver represents the most immediate upcoming maneuver, while nextManeuver represents the next most immediate upcoming maneuver. Maneuvers contain road-related information such as road name, the turn to be taken, and the maneuver orientation.

currentManeuver and nextManeuver may not be always readily available. You can use the navigationManager:hasCurrentManeuver:nextManeuver: method in the NMANavigationManagerDelegate protocol to receive notifications when maneuvers have been updated. For more information, see the section about NMANavigationManagerDelegate.

You can take advantage of the lowSpeedOffset, highSpeedOffset, speedBoundary, and speedWarningEnabled properties to set up the speed warning feature. When speed warning is enabled, the navigationManager:didUpdateSpeedingStatus:forCurrentSpeed:speedLimit notification is sent to the navigation manager delegate when the boundary plus an offset has been violated. The speed warning feature is enabled by default.

Note: The NMANavigationManager only returns car speed warnings. Truck speed warnings are not currently supported.

Map Tracking

NMANavigationManager also provides properties for customizing map tracking. Map tracking refers to the ability for the map location to be automatically updated during navigation. By default, the map tracking feature is enabled, but it can be toggled through the mapTrackingEnabled property. When tracking is enabled, you can use the mapTrackingOrientation property to set whether the map is oriented dynamically or always pointed North. You can also set whether the map automatically adjusts the zoom level, based on the current device speed, by using the mapTrackingAutoZoomEnabled property. By default, dynamic orientation and auto zoom are enabled.

After starting NMANavigationManager in Navigation or Tracking mode, you can move the positionIndicator closer to the bottom of the screen by changing the transformCenter property in NMAMapView. Having the transformCenter at the bottom of the screen ensures that the route and turning animations are more visible to the user.

Natural Guidance

The 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"

The available types of natural guidance information are defined by the NMANaturalGuidanceOption enum. These options may be used individually or used in combination, although typically, only a single type of guidance instruction would be given for a particular maneuver. To disable natural guidance, pass NMANaturalGuidanceNone to the setNaturalGuidanceMode: method.

Note: While using the NMANaturalGuidanceLandmark option, the device locale and navigation voice package language should be set to match the user's physical location. Otherwise, landmark information may not be spoken. For example, while navigating in a country that uses French as its spoken language, the voice package and the device locale should be set to French.

The NMANavigationManagerDelegate protocol

NMANavigationManager notifies the client of navigation events through its delegates that implement the NMANavigationManagerDelegate protocol. The delegate protocol include methods such as:
  • navigationManagerDidReachDestination: - Signifies that the destination of the navigation was reached
  • navigationManager:hasCurrentManeuver:nextManeuver: - Signifies that there is new instruction information available that can be fetched by accessing the 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:shouldPlayVoiceFeedbackWithText: - Signifies that a voice feedback is ready to be played. Use this callback's 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

Lane Information

The NMANavigationManagerDelegate also provides the navigationManager:didUpdateLaneInformation:roadElement: method. This callback occurs when the user has arrived at a point in the route where lane information should be presented, such as before a highway exit. The NMALaneInformation class represents a lane turn direction and whether this lane is on the current route. For example, an application may receive the navigationManager:didUpdateLaneInformation:roadElement: callback as the user navigates to an intersection. If the route requires a left turn, and the current road has three lanes—a left-turn lane and two straight lanes—then the callback contains three NMALaneInformation objects. Since NMALaneInformation objects are always returned in the callback method in a left-to-right order, the first NMALaneInformation has a directions property as "left" and the recommendationState property, which indicates whether the lane is on the current route. If there isn't enough data to determine whether the lane is on or off-route, the recommendationState property returns NMALaneInformationRecommendationStateNotAvailable.

Realistic View: 2D Signposts and Junction View

In addition to the data offered through the Lane Info feature, your application can also use the HERE iOS SDK to offer image previews of signposts and junctions on certain highways. For example, as a user approaches a fork on a highway, your application can show a preview of two instruction signs above the highway and the lanes near the junction, with indicator arrows highlighting the correct lanes. These image preview are known as 2D Signposts and Junction View, and together they are known as Realistic View.

Figure 3. An Example of a 2D Signpost
Figure 4. An Example of a Junction View

The Realistic View feature is disabled by default. To enable it, use the NMANavigationManager.realisticViewMode property and set the view mode to NMARealisticViewDay or NMARealisticViewNight. Next, register the desired image aspect ratios by using the NMANavigationManager.realisticViewAspectRatios property.

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 the NMANavigationManagerSignpostKey and NMANavigationManagerJunctionViewKey keys.
Note: It is possible to add multiple aspect ratios and receive multiple images of the same signpost or junction view. However, please be aware that this may cause some performance impact.
Note: To dismiss the Realistic View images, your navigation manager delegate should also implement and listen for the navigationManagerDidInvalidateRealisticViews: method. This method is called when realistic view images should be dismissed (for example, after the user has entered the junction).

The following is an example of a navigationManager:didUpdateRealisticViewsForCurrentManeuver: implementation:


- (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
  }
}

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.