SDK for iOS Developer's Guide

Advanced Positioning by HERE

In addition to the basic positioning services SDK for iOS provides advanced HERE Positioning with the following key features:
  • High accuracy indoor positioning with building and floor detection using Bluetooth™ radio
  • Automatic, on-demand download of radio positioning data (radiomaps) for positioning without network connection (offline)
  • Automatic positioning method switching between satellite-based (Global Navigation Satellite System, GNSS) and Bluetooth positioning, providing the best possible position information using the available position methods
  • HERE Indoor Positioning supports both private and public data. You can have a private venue that is mapped through HERE Private Venues or your own custom indoor map, with the indoor location information being only available for your applications. In contrast, indoor location information for public venues is available for all HERE SDK users with an appropriate license
  • Global data hosting infrastructure for the optimal availability, reliability, and user experience

HERE Indoor Positioning information

To use HERE Indoor Positioning, indoor positioning support must be deployed to a venue. To do this, please visit indoor.here.com. All the required information to setup HERE Indoor Positioning is available there. Especially familiarize yourself with HERE Indoor Positioning Installation Guide.

After the deployment HERE Indoor Positioning can use Bluetooth radio for indoor positioning. Due to the differences in the iOS device capabilities, HERE Indoor Positioning performance may differ between the device models and iOS versions.

Wi-Fi -based indoor positioning is not supported in iOS due to the platform and operating system limitations.

HERE Positioning Feature Groups

HERE Positioning is split into features groups. Depending on your business plan, you have an access to one or more of the following feature groups:
  • Private Indoor - This feature provides high accuracy indoor positioning for private venues from which indoor Bluetooth radio data has been collected using HERE Indoor Radio Mapper. The feature provides indoor positioning capability that is accessible only by the owner of the positioning data. You can find further details in HERE Indoor Positioning Installation Guide.
  • Public Indoor - This feature provides high accuracy indoor positioning for public venues from which indoor Bluetooth radio data has been collected using HERE Indoor Radio Mapper. The feature uses HERE Indoor Positioning community radiomap that is accessible by all the SDK for iOS users having access to this feature. Further details can be found in HERE Indoor Positioning Installation Guide.

HERE Indoor Positioning (private and public) works by utilizing downloaded positioning assistance data, such as radiomaps, for position estimation within the device. Network connectivity is only required for the radiomap download after which no connectivity is needed unless further radiomap tiles are needed.

Radiomap download is handled by the on-demand downloader which automatically downloads radiomap tiles in the vicinity of the device. The downloader also maintains radiomaps on the device by updating the radiomap tiles at regular intervals as needed and by removing the oldest radiomap tiles when the radiomap tiles exceed the storage quota. This quota is configured as speficied in the table below. The table also shows how often SDK for iOS attempts to update the radiomaps.

Technology Quota Update interval Description
Indoor Bluetooth 32MB 7 days Contains high accuracy radiomaps for indoor Bluetooth positioning

Using HERE Positioning

To start using HERE Positioning in your iOS applications, perform the following steps:

  1. Find Capabilities tab in the Xcode project settings and enable Background Modes for Location Updates and Uses Bluetooth LE accessories.
  2. Declare Private Data Access and App Transport Security exceptions by updating Info.plist of the app. See App Submission Requirements for more details.
  3. After completing the previous configuration steps you can change the positioning manager data source to HERE Positioning with the following code:
    
                          NMAPositioningManager.sharedPositioningManager.dataSource = [[NMAHEREPositionSource alloc] init];
                        

Running HERE Positioning in background

To make HERE Positioning run in background, add the following line to the app delegate function applicationDidBecomeActive:

            [NMAPositioningManager.sharedPositioningManager.dataSource setBackgroundUpdatesEnabled:true];
            
Moreover, ensure that your Info.plist has the following attributes:
<key>NSLocationAlwaysUsageDescription</key>
<string>This application uses location information</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>This application uses location information</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This application uses location information</string>

<key>NSMotionUsageDescription</key>
<string>This application uses motion sensors for indoor positioning</string>

<key>NSBluetoothPeripheralUsageDescription</key>
<string>This application uses Bluetooth for indoor positioning</string>

<key>UIBackgroundModes</key>
<array>
   <string>bluetooth-central</string>
   <string>location</string>
</array>

Indoor Positioning Mode

The indoor positioning mode refers to the set of radiomaps used by the indoor positioning engine. For detailed discussion on the different radiomaps please refer to HERE Indoor Positioning Installation Guide.

Indoor positioning can be configured to run in four different modes which are defined by NMAIndoorPositioningMode enumeration. Use the property indoorPositioningMode on the NMAHEREPositionSource interface to change the indoor positioning mode. You can use the same property to check the current mode.

The following table introduces the four indoor positioning modes.

Table 1. Indoor Positioning Modes Supported by HERE Positioning
Mode Description
AUTOMATIC HERE Positioning automatically chooses which mode to apply. Requires that the SDK license has both public and private indoor positioning features enabled. If both features are enabled in the SDK license, then this positioning mode is set as the default.
COMMUNITY Community indoor radiomap is used by the indoor positioning engine. Requires an SDK license with the public indoor positioning feature enabled. If only the public indoor positioning feature is enabled in the SDK license, then this indoor positioning mode is set as the default.
PRIVATE A private indoor radiomap is used by the indoor positioning engine. Requires an SDK license with the private indoor positioning feature enabled. If only the private indoor positioning feature is enabled in the SDK license, then this indoor positioning mode is set as the default.

Indoor Positioning-specific Properties

HERE Positioning has three indoor positioning-specific properties in NMAGeoPosition:

  • NSString buildingName

    Contains the building name, if known. If the building name is not present or unknown, it is set to nil.

    For HERE Venue Maps the building name is assigned by HERE when creating the Venue Map.

    For custom indoor maps the building name is the one given when the indoor map was imported using HERE Indoor Radio Mapper. However, illegal characters are removed from the name.

  • NSString buildingId

    Contains the building ID, if known. If the building ID is not present or unknown, it is set to nil.

    For HERE Venue Maps the building ID is a globally unique ID assigned by HERE when creating the Venue Map. An example of a HERE Venue Map building ID is DM_8213.

    For custom indoor maps the building ID is a user-defined buildingName prefixed with "BM_".

    If the position estimate is outdoors but indoor positioning is used for producing the location estimate, the building ID string is populated as OUTDOOR.

  • NSNumber floorId

    Contains the floor level information. If the floor ID is unknown or not present, it is set to nil.

    For HERE Venue Maps the floor levels are returned as defined for the particular HERE Venue Map.

    For the custom indoor maps the floor level follows the floor levels specified in HERE Indoor Radio Mapper when the indoor maps were imported.

Hints for HERE Positioning API usage

Troubleshooting HERE Positioning

If your application does not receive any position updates while using HERE Positioning, try the following:

  • Check that the application has Capabilities set in Xcode as defined in this document. See Using HERE Positioning.
  • Check that the application has Private User Data Access declarations set in Xcode as defined in this document. See Using HERE Positioning.
  • Make sure that the relevant network settings are enabled:
    • Go to the device Settings and check that Bluetooth is enabled
    • Go to Settings and check from the application settings that Location Access is set to Always and that Motion and Fitness and Mobile Data access is enabled.
  • Make sure that the device has a network connection.
  • Make sure the indoor positioning mode is set correctly.

If your application receives inaccurate position estimates while using HERE Positioning, try the following:

  • Make sure that the location estimates originate from the indoor positioning engine by checking the position source through the source property in NMAGeoPosition.