NMAPositioningManager

The NMAPositioningManager class provides information related to the device's geographical location, such as the current position and the average speed. NMAPositioningManager is a singleton class and thus should only be accessed through the sharedPositioningManager class method.

To start receiving real time positioning updates, the application needs to call NMAPositioningManager startPositioning, which uses the internal GPS as the update mechanism. This method returns a BOOL value, indicating whether or not positioning was successfully started.

While position updates are being received, the application can retrieve the current position of the client device through the NMAPositioningManager currentPosition property. This current position is equal to the rawPosition property. rawPosition is a position value from the current data source that has not been modified by the HERE SDK engine. If the positioning manager is not active, or it has an invalid position, then the currentPosition method returns nil.

When the application no longer requires position updates, it should notify the NMAPositioningManager by calling stopPositioning. Position updates are then stopped, provided that no other SDK services (such as NMAPositionIndicator) that require position updates are in use.

NMAPositioningManager Notifications

The NMAPositioningManager notifications can be used to track position updates of a client device as determined by its positioning mechanism (for example, its GPS). To register or unregister for these notifications, use the following methods:

[[NSNotificationCenter defaultCenter] addObserver:self
    selector:@selector(methodName)
      name:NMAPositioningManagerDidUpdatePositionNotification
      object:[NMAPositioningManager sharedPositioningManager]];

[[NSNotificationCenter defaultCenter] removeObserver:self
      name:NMAPositioningManagerDidUpdatePositionNotification
    object:[NMAPositioningManager sharedPositioningManager]];

Applications can register for two types of notifications:

• NMAPositioningManagerDidUpdatePositionNotification
• NMAPositioningManagerDidLosePositionNotification

The following is an example of registering and handling these notifications in a UIViewController:

// Start positioning and register for position update notifications
- (void)viewDidLoad
{
  ...
  if ([[NMAPositioningManager sharedPositioningManager] startPositioning]) {
  // Register to positioning manager notifications
  [[NSNotificationCenter defaultCenter] addObserver:self
    selector:@selector(positionDidUpdate) name:NMAPositioningManagerDidUpdatePositionNotification
    object:[NMAPositioningManager sharedPositioningManager]];

  [[NSNotificationCenter defaultCenter] addObserver:self
    selector:@selector(didLosePosition) name: NMAPositioningManagerDidLosePositionNotification
    object:[NMAPositioningManager sharedPositioningManager]];
  }

  ...
}
// Handle NMAPositioningManagerDidUpdatePositionNotification
- (void)positionDidUpdate
{
  NMAGeoPosition *position = [[NMAPositioningManager sharedPositioningManager] currentPosition];
  [_mapView setGeoCenter:position.coordinates
        withAnimation:NMAMapAnimationLinear];
}
// Handle NMAPositioningManagerDidLosePositionNotification
- (void)didLosePosition
{
  ...
}

To avoid unnecessary position updates while the application is in the background, you can stop positioning and restart it when the application returns to the foreground using UIApplicationDelegate protocol callbacks.

The following code snippet demonstrates how to stop positioning and unregister from the notifications:

- (void)viewWillDisappear:(BOOL)animated
{
  [[NMAPositioningManager sharedPositioningManager] stopPositioning];
  [[NSNotificationCenter defaultCenter] removeObserver:self
    name:NMAPositioningManagerDidUpdatePositionNotification
    object:[NMAPositioningManager sharedPositioningManager]];
  [[NSNotificationCenter defaultCenter] removeObserver:self
    name:NMAPositioningManagerDidLosePositionNotification
    object:[NMAPositioningManager sharedPositioningManager]];
}

Creating Position Logs

You can also use the HERE SDK to create GPX logs that can be replayed by NMALoggedPositionSource. To do this, set the logType property in NMAPositionManager to the value NMAPositionLogTypeDataSource, indicating that the position received from the current data source should be logged. GPX logs are created in the Documents folder of your application. To disable position logging, set NMAPositionLogType to NMAPositionLogTypeNone.

NMAPositionIndicator

The NMAPositionIndicator class provides a convenient way to add a map object that marks the user's current location as reported by the NMAPositioningManager. The position indicator is rendered as a circular object within a translucent circle, the diameter of which illustrates the accuracy of the indicated position. The types of map objects can be used to customize NMAPositionIndicator are NMAMapMarker and NMAMapCircle.

Figure 1. An NMAPositionIndicator

Each NMAMapView instance has an NMAPositionIndicator instance which can be accessed from the NMAMapView positionIndicator property.

You can customize the accuracy circle's color and whether it is visible by using the accuracyIndicatorColor and accuracyIndicatorVisible properties.

// Display position indicator
mapView.positionIndicator.visible = YES;