HERE iOS SDK Developer's Guide

Advanced Positioning by HERE

In addition to the basic positioning services, HERE iOS SDK 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.

Wi-Fi -based indoor positioning is not supported in iOS due to 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 HERE iOS SDK 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 the 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 the HERE iOS SDK 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:

Find the Capabilities tab in the Xcode project settings and enable Background Modes for Location Updates and Uses Bluetooth LE accessories
Declare Private Data Access and App Transport Security exceptions by updating Info.plist of the app. See App Submission Requirements for more details.

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 backgound

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>Location information is needed to use this application</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location information is needed to use this application</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Location information is needed to use this application</string>
<key>NSMotionUsageDescription</key>
<string>This is needed for bluetooth based 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 the NMAIndoorPositioningMode enumeration. Use the property indoorPositioningMode on the NMAHEREPositionSource interface to change the indoor positioning mode. You can use the same propertyto check the current mode.

The following table introduces the four indoor positioning modes.

Table 1. Indoor Positioning Modes Supported by the 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 a 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 a 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 as 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 as nil.

For HERE Venue Maps, the building ID is the 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 the 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 as 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 the HERE Positioning API usage

When using HERE Positioning for indoor positioning, the positioning API will return non-indoor location for the first few seconds even when in a venue with indoor positioning coverage. In such a case, one option is to discard the non-indoor locations for the first few seconds in the application start-up.
An iOS tutorial projects are available through GitHub at https://github.com/heremaps/here-ios-sdk-examples/tree/master/here-positioning-ios (Obj-C) and https://github.com/heremaps/here-ios-sdk-examples/tree/master/here-positioning-ios-swift (Swift). The project helps you to get your first HERE Positioning application up and running smoothly.

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.

HERE iOS SDK