HERE Android 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
VenueManeuver.setNaturalGuidanceRadius(10.0);
//Get the natural guidance POI of a maneuver
floar naturalGuidanceRadius = VenueManeuver.getNaturalGuidanceRadius();
//If there is no suitable POI in the specified radius around the maneuver,
//the returned string will be empty.
String naturalGuidance = myManeuver.getNaturalGuidancePOI();

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 VenueLayerAdapter.getNavigationManager(). 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 com.here.android.mpa.venues3d.VenueNavigationManager;
import com.here.android.mpa.venues3d.VenueNavigationManager.VenueNavigationManagerListener;
import com.here.android.mpa.venues3d.CombinedRoute;
import com.here.android.mpa.venues3d.VenueManeuver;
import com.here.android.mpa.venues3d.VenueRoute;

class VenueNavigationExample implements VenueNavigationManagerListener {

  /**
  * Called when the destination of turn-by-turn navigation is reached.
  */
  /*
  * When the destination is reached, {@link VenueNavigationManager#stop} is automatically
  * called. When this callback is received, the navigation manager state will be {@link
  * NavigationState#IDLE}.
  */
  @override
  void onDestinationReached() {
  }

  /**
  * Called when the current (upcoming) maneuver is updated.
  *
  * 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.
  *
  * @param maneuver The current (upcoming) maneuver to be made.
  * @param nextManeuver The maneuver to be made AFTER THE CURRENT MANEUVER.
  */
  @override
  void onCurrentManeuverChanged(VenueManeuver maneuver, VenueManeuver nextManeuver) {
    String guidance = maneuver.getNaturalGuidancePOI();
    if (guidance.isEmpty()) {
      System.out.println("maneuver without natural guidance");
    } else {
      System.out.println("maneuver natural guidance: " + guidance);
    }
  }

  /**
  * Called when the navigation manager loses its indoor position.
  */
  @override
  void onPositionLost() {
  }

  /**
  * Called when the navigation manager finds its indoor position.
  */
  @override
  void onPositionRestored() {
  }

  /**
  * 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
  * {@link VenueNavigationManagerListener#onRerouteBegin()}).
  *
  * @param routeSection
  *        VenueRoute representing the route section that was set.
  * @param combinedRoute
  *        CombinedRoute representing the current route.
  */
  @override
  void onRouteSectionUpdated(VenueRoute routeSection, CombinedRoute 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
  * {@link VenueNavigationManagerListener#onRouteSectionUpdated(VenueRoute, CombinedRoute)}
  * is called. After rerouting, the {@link VenueNavigationManagerListener#onRerouteEnd()}
  * is called.
  */
  @override
  void onRerouteBegin() {
  }

  /**
  * 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.
  */
  @override
  void onRerouteEnd() {
  }

}

This class can be registered with the venue navigation manager by invoking venueNavigationManager.addListener(new VenueNavigationExample()).

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 VenueLayerAdapter.getCombinedNavigationManager(). 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 com.here.android.mpa.venues3d.CombinedNavigationManager;
import com.here.android.mpa.venues3d.CombinedNavigationManager.CombinedNavigationManagerListener;
import com.here.android.mpa.venues3d.CombinedRoute;
import com.here.android.mpa.venues3d.LinkingRoute;
import com.here.android.mpa.venues3d.OutdoorRoute;
import com.here.android.mpa.venues3d.RoutingController;
import com.here.android.mpa.venues3d.VenueLayerAdapter;
import com.here.android.mpa.venues3d.VenueRoute;

class CombinedNavigationExample implements CombinedNavigationManagerListener {

  VenueLayerAdapter m_venueLayer;

  /**
  * Called when the destination of turn-by-turn navigation is reached.
  */
  /*
  * When the destination is reached, {@link CombinedNavigationManager#stop} is automatically
  * called.
  */
  @override
  void onDestinationReached() {
  }

  /**
  * Called when a change is made to the route being navigated.
  *
  * This can occur after successful rerouting due to the user leaving the current route.
  *
  * @param combinedRoute
  *        CombinedRoute representing the current route.
  */
  @override
  void onRouteUpdated(CombinedRoute combinedRoute) {
    // Show route.
    RoutingController routingController = m_venueLayer.getRoutingController();
    routingController.showRoute(combinedRoute);
  }

  /**
  * Called when an indoor section of the combined route will be started.
  *
  * @param indoorSection VenueRoute representing the next indoor section.
  * @param combinedRoute CombinedRoute representing the current route.
  */
  @override
  void onIndoorSectionWillStart(VenueRoute indoorSection, CombinedRoute combinedRoute) {
  }

  /**
  * Called when an outdoor section of the combined route will be started.
  *
  * @param outdoorSection OutdoorRoute representing the next outdoor section.
  * @param combinedRoute CombinedRoute representing the current route.
  */
  @override
  void onOutdoorSectionWillStart(OutdoorRoute outdoorSection, CombinedRoute combinedRoute) {
  }

  /**
  * Called when an link section of the combined route will be started.
  *
  * @param linkingSection LinkRoute representing the next link section.
  * @param combinedRoute CombinedRoute representing the current route.
  */
  @override
  void onLinkingSectionWillStart(LinkingRoute linkingSection, CombinedRoute combinedRoute) {
  }

}

This class can be registered with the combined navigation manager by invoking combinedNavigationManager.addListener(new CombinedNavigationExample()).

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.setBeepsEnabled(true).

To enable haptic feedback on maneuver events, invoke venueNavigationManager.setVibrationEnabled(true).

See the API documentation of VenueNavigationManager 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.setManeuverZoomEnabled(true).

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

Set the zoom level to which maneuver zoom will zoom in in the vicinity of a maneuver to 20 by invoking venueNavigationManager.setManeuverZoomLevel(20).

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