Migration Guide

This guideline provides a set of steps to migrate from another HERE SDK edition to the Explore Edition or Navigate Edition. Note that not all features of the Navigate Edition are available for the Explore Edition. The Explore Edition is a subset of the Navigation Edition.

When you plan to migrate from a different SDK like Mapbox or Google Maps it is recommended to take a look at the Key Concepts section. Here you can find the most common concepts that are unified across the Lite, Explore & Navigate Editions. The differences between these editions are listed in the Overview section of this guide.

Overview

Unless for very small projects, migrating an app from one edition to another requires time and may introduce breaking changes to your customers. To minimize the effort, we recommend an incremental approach:

1. Before you start, learn more about the availability of the features. Please consult the "Feature comparison for the HERE SDK" list you can find on the HERE SDK launch page. If a feature is not available for the targeted edition, consult your HERE representative. It may be already planned for one of the next regular releases.

2. Check the available plans for the new edition. You can freely start using the HERE SDK. An overview of the available plans can be found on the pricing page. More details on the plans can be found in our FAQs.

3. Request a new set of credentials from your HERE representative. Credentials are not interchangeable between editions. For now, the Navigate Edition is only available upon request.

4. Start to migrate. This is covered in more detail in the sections below.

Migration Strategies

Depending on the complexity of your app, it may not be necessary to start from scratch. Instead, consider to create a copy of your existing project and start to migrate the features step-by-step.

There are several different strategies possible to successfully complete the migration of your app. One possible strategy could be the following:

1. Deintegrate the old SDK framework first.

2. Then integrate the new SDK framework by following the Get Started section.

3. Finally, fix the remaining compile errors of your legacy code by adapting to the new APIs and start testing. Unit and integration tests may help.

As a tip, it may help if your code is implemented against interfaces to keep your code decoupled from a specific library. This way it will be easier to comment out legacy code and replace it feature-wise instead of producing countless compile errors once a library is de-integrated.

In addition, make sure to get familiar with the 4.x Developer Guide: Besides covering coding examples for all core features, it contains also useful tips on how to optimize an application for release. Find more in our Optimization Guide.

Below you can find more details on the needed migration steps per edition.

Migrate from Explore to Navigate Edition

No migration work is needed. The Explore Edition is a subset of the Navigate Edition and thus the code will compile and behave as before. You only need to replace the framework folder (which is usually placed inside the app's folder) and insert your new credentials into the Info.plist file. Request new credentials from your HERE representative. For now, the Navigate Edition is only available upon request.

Migrate from Lite to Explore Edition

Please read the next section. The Explore Edition is a subset of the Navigation Edition. Although you need to replace the library inside the app's libs folder, you can keep the same credentials: The credentials of the Lite Edition and the Explore Edition are interchangable.

Migrate from Lite to Navigate Edition

All map view related code may need adaptation, as the Lite Edition uses a light-weighted map renderer. When switching to the Navigate Edition, the MapViewLite must be replaced with a MapView to benefit from the powerful features of the HERE Rendering Engine. The good news is that all other code can stay the same as it already shares the same native code base with the Navigate Edition.

1. Start by replacing the MapViewLite with MapView.

2. Follow the Get Started guide to properly load the map view. It's almost identical to the Lite Edition.

3. If you are using a *.storyboard to integrate the map view, replace all occurences of MapViewLite with MapView. Open the file "as source code" to do a quick search-and-replace.

4. The MapStyle schemes available for the Lite Edition are replaced by MapScheme styles. Note that the .normalDay and .satellite styles are available for both editions. Consult the API Reference to see the additional predefined map styles that are available for the Navigate Edition.

5. Custom map styles use a different style format and are not interchangeable. Read the Custom Map Styles section to learn more about the advanced capabilities of the HERE Style Editor.

6. Consult the Map Items section to grab ready-to-use code snippets and to learn how to add items to the map view. The Navigate Edition supports the same set of map items as the Lite Edition. MapOverlay views have been renamed to MapViewPin. Note that a few features that are available in the Lite Edition are not yet available for the Navigate Edition, for example, a rotation of MapMarker items is not yet supported. The above section provides an overview of what is currently available.

7. Read the Camera section to see the differences and advanced capabilities available for the Navigate Edition. The MapCamera allows full 3D camera control and many more exciting features.

To help you with migration, you can find the same set of example apps available for the Lite Edition already ported to the Explore Edition or Navigate Edition on GitHub.

Migrate from Premium to Explore Edition

Please read the next section. The Explore Edition is a subset of the Navigation Edition. Note that the credentials of the Explore Edition and the Navigate Edition are not interchangable. For the Explore Edition, you can get get credentials via self-serve as described in the Get Started section.

Migrate from Premium to Navigate Edition

Unlike the other editions, the Starter and Premium Edition share a completely different technology stack and thus, the new SDK editions Lite, Explore & Navigate are completely built from scratch. This results in different APIs, concepts and behaviors.

As a result, this means that there is no 1:1 conversion possible.

To get familiar with the main differences check the functionality entry points. When planning to migrate, make sure to plan enough resources to test your app before & after the migration.

Follow the use cases described in this Developer Guide to get a first overview. Also, take a look at the Key Concepts section. Here you can find the most common concepts that are unified across the Lite, Explore & Navigate Editions. Check the Premium and Navigate differences section for a side-by-side comparison.

In many cases, the migration from Premium to Navigate Edition may start with the basic map initialization. When the map initialization migration is completed, you can continue with other functionality that is available in your application.

You can find a set of example apps available for the Navigate Edition on GitHub.

Since the Starter Edition is a sub set, it is not explicitly included in this migration guide. However, most of the sections below can be also applied when migrating from Starter to Navigate Edition - or when migrating to the Explore Edition instead of the Navigate Edition.

Why Should I Migrate?

The new Lite, Explore & Navigate Editions are built completely from scratch to ensure support for the latest HERE technology stack. In comparison to the Starter and Premium Editions you gain the following benefits:

• Consume data from the HERE platform incorporating microservices and modularized components enabling most seamless switches from one edition to another.
• Optimized size and performance.
• Advanced map rendering and customization capabilities.
• Freshest map data with weekly map updates.
• Leverage new HERE platform services that are only supported with the new editions.

A few features that are exclusively available for 4.x:

• Support for bring your own data (BYOD).
• Support for custom backends and map catalogs (self hosting).
• Support for new markets like Japan.
• Support for electric vehicles.

Feature List

Before you start, learn more about the availability of the individual features for each edition. Please consult the "Feature comparison for the HERE SDK" list you can find on the HERE SDK launch page. In addition, compare the more granular Navigate feature list with the Premium feature list, that are available as part of the respective user guides.

Missing Features

In comparison to the Premium Edition, there are a few features that are not yet implemented for the Navigate Edition. This includes:

• Environmental zone warning: Expected to be delivered in Q2 2023.
• Polyline styling with dots: Expected to be delivered in Q2 2023.
• School zone warner: Expected to be delivered in Q3 2023.

If any of these features are critical for your app, consider not migrating yet.

The following features of the 3.x Premium Edition are deprecated and therefore discontinued:

• Electronic Horizon: HERE does not contractually allow the integration of Electronic Horizon of the 3.x Premium Edition into vehicle controls nor to use the current ADASIS v2 protocol directly. Instead, the HERE SDK team plans to expose a most probable path calculator to inform on driving related events ahead so that customers can build the same use cases with the 4.x Navigate Edition.
• Offline public transit routing: This feature is deprecated as the accuracy of offline timetable routing is not high enough. Therefore, the 4.x HERE SDK supports getting public transport directions only in online mode.
• Objective-C: Currently, we do not support Objective-C and it is not possible to use bridging headers. If your code-base is written in Objective-C, consider to migrate to Swift. However, it is possible to access the HERE SDK directly from Swift files that are integrated into an existing Objective-C project. It is possible to mix Swift and Objective-C in a single project, but for now you cannot access the HERE SDK directly from Objective-C.
• Background rendering: This 3.x feature is deprecated and will not be supported for the 4.x HERE SDK. Therefore, a 4.x counterpart for snapshotWithBlock and snapshotWithGeoCoordinates:zoomLevel:orientation:size:block: (see NMAMapView) will not be made available.
• Pre-recorded voices for TTS: Pre-recorded voice files have been deprecated. The 4.x HERE SDK supports multiple languages to support TTS engines, but it provides these texts only as Strings, so that developers have to choose a platform solution to play-back these texts with an engine of their choice. The navigation section shows an example how to do this.

Replaced features

The following features from 3.x are not directly supported in 4.x and are replaced by alternative BYOD ("bring your own data") solutions. Please talk to your respective account manager or contact our HERE support team for more information:

• Custom Location Extension 2 (CLE2) / CLE2 Offline: This feature is replaced with BYOD for search and geocoding. With the MyPlaces class, custom data can be imported. For more details on the new BYOD concept, take a look at the 4.x search guide.
• Custom router extension: This feature is replaced by a new custom data concept to support the BYOD use case, similar as for search and geocoding with MyPlaces (see above).
• Platform Data Extension (PDE): This feature is replaced by a new custom data concept.
• Fleet Telematics Custom Routes (FTCR): This feature is replaced by a new custom data concept.

Credentials

Start by acquiring new credentials. For the Navigate Edition you need to contact your HERE representative to generate a set of evaluation credentials.

In contrast to the Premium Edition, the Navigate Edition uses a different type of credentials. APP ID, TOKEN and LICENSE ID are not needed, instead you need two strings:

• ACCESS KEY ID
• ACCESS KEY SECRET

The acquired credentials can be reused for the Lite and Explore Editions regardless of the platform - furthermore, you can use these credentials for more than one app. For example, they will work with all example apps you can find on GitHub.

SDK Dependency Management

The Lite, Explore & Navigate Editions do not yet provide artifactory support via CocoaPods. This means that you must manually download and integrate the HERE SDK framework folder (XCFW) as described here.

Engines

Most notably, all features within the Lite, Explore & Navigate Editions are built around engines. To look for certain features, it's best start finding the related engine in the API Reference and consult the related chapter within this user guide to get an overview.

Note that not all engines are available for the Lite & Explore Edition.

• SearchEngine: Includes all functionality to search for places, suggestions and locations including geocoding and reverse geocoding.
• OfflineSearchEngine: The offline version of search that makes request locally using already downloaded map data.
• RoutingEngine: Allows to calculate routes including various options and transport types.
• OfflineRoutingEngine: The offline version that calculates a route using already downloaded map data.
• LocationEngine: An advanced HERE positioning solution.
• ConsentEngine: A supportive engine that helps to aggregate the user's consent before using, for example, the LocationEngine.
• Navigator / VisualNavigator: Although not having 'engine' in its name, these classes act as an engine and control all functionality around turn-by-turn navigation.
• DynamicRoutingEngine: An engine that periodically searches for shorter or faster routes based on the current traffic situation. This can be useful during guidance to notify drivers on route alternatives.
• TrafficEngine: An engine that allows to search for traffic incidents.
• MapDownloader / MapUpdater: These classes perform downloads or updates of map data and mark a vital part of any application that supports an offline mode.
• VenueEngine: A specialized engine to support the integration of private venues into your apps.
• SDKNativeEngine: Is required to setup credentials programmatically and allows a few other advanced settings.

Take a look at the migration entry points and map initialization sections for a migration quick start.

All map related features are grouped around the MapView class. Note that you can fully operate the HERE SDK in a headless mode without showing a map.

Counting Monthly Active Users (MAU)

Depending on your plan the HERE SDK charges based on the number of transactions per month and other parameters such as monthly active users (MAU).

Legacy App Data

Usually, a fully migrated app will be updated on a device that already contains installed data. Make sure to preserve, convert or delete the data where applicable.

• The Premium Edition stores all map related data into a ".here-maps" folder.
• It is recommended to delete this folder - if present.

Note that the 4.x HERE SDK cannot read or delete the ".here-maps" folder on its own. The folder is located inside the app's directory: A user can manually browse and delete the folder, or it can be accessed and deleted by the application itself.

Map View

The Explore Edition and the Navigate Edition feature an advanced HERE Rendering Engine that offers visually appealing true 3D maps that provide highly performant map rendering tailored for high-end devices. Take a look at the Key Concepts section for more details.

• To integrate the MapView, follow the Get Started guide to properly load the map view.

• The visual representation of the MapView can be changed with predefined MapScheme styles or custom map styles. More information is available in the Map Styles section.

• Read the Map Items section to grab ready-to-use code snippets and to learn how to add items to the map view. The above section provides an overview of what is currently available.

• Read the Camera section to get an overview of the differences and advanced capabilities of the Navigate Edition. The MapCamera allows full 3D camera control and many more exciting features. Note that the Navigate Edition also provides zoom levels, but the actual level of detail may differ. In addition, the Navigate Edition uses the distance to earth to position the camera above the map as this allows more precise results.

To complement this section, read also the Gestures & Traffic sections to know about the available map view behavior. Certain other map features like marker clustering, custom raster tiles, 3D landmarks or animations are not yet available.

To add customized zoom in/out map animations you can overwrite the .doubleTap .and twoFingerTap gestures:

mapView.gestures.disableDefaultAction(forGesture: .doubleTap)
mapView.gestures.disableDefaultAction(forGesture: .twoFingerTap)

// ...

// Conform to the DoubleTapDelegate protocol.
func onDoubleTap(origin: Point2D) {
    // Start your custom zoom in animation.
}

// Conform to the TwoFingerTapDelegate protocol.
func onTwoFingerTap(origin: Point2D) {
    // Start your custom zoom out animation.
}

In the Gestures section you can find a tutorial how this can be implemented.

Map Camera

The Camera object inside the MapView instance provides a new concept for Premium Edition edition users. In general, it can be associated as user point of view, which can be changed using different actions. These actions already existed in Premium Edition as, for example, tilt, zoom, boundingBox, and other properties of NMAMapView, and some of them are new - like distance to earth - or renamed.

The MapView shows the MapScene from a configured position of the Camera. The Camera itself doesn't change the MapScene objects, it just represents a 3D scene from a given position.

The Camera has a principlePoint property that is also known as transformCenter for Premium Edition users. The difference is that tranformCenter takes relative coordinates in the range {[0, 1], [0, 1]}, where {0, 0} is representing the upper-left corner of the map and {1, 1} the lower-right corner. The default tranformCenter value is {0.5, 0.5}, which is centered on both, width and height. While the principlePoint takes the pixel value in a range of the MapView's size on screen in pixels. An example for a possible principle point adjustment is described in the Change the Tranform Center section.

Map Layers

The Layer term stands for the visual data with common criteria, which can be represented on a MapView. A MapScene can represent multiple map layers at the same time. The Layer visibility is controlled with mapScene.setLayerVisibility(layerName: newState:). It is a synchronous call which results in the given state. The state can be .visible or .hidden. The existing layerNames are defined in a Layers structure.

An example of Layers usage is shown in the Traffic section.

Map Items

An entry point to add map items is MapScene, which is accessible from MapView using a .mapScene call.

The NMAMapCircle and NMAMapRoute are not available in the Navigate Edition.

• Instead of NMAMapCircle, please use a MapPolygon that uses GeoCircle geometry points.
• For NMAMapRoute the MapPolyline is the recommended type to render the GeoPolyline of the Route.

For MapMarker image creation, use the MapImage class, which can be instantiated from UIImage PNG data - see this Github example for more details.

In addition to MapMarker, the user can show native UIView objects anchored to the map. It is enough to set the custom UIView-based content into a special ViewPin object and anchor it to the map.Premium Edition users might know this special object class as NMAMapOverlay.

A more detailed ViewPin description and example can be found in the Add Map View Pins section.

Map Styles

The MapView of the Navigation Edition can be rendered using different predefined MapSchemes. For example: day, night, satellite, and more. Consult the API Reference to see the all the available styles. Also, the map customization can be done using a dedicated HERE Style Editor, which is not available for the Premium Edition.

To create custom map styles you may want to:

• Define colors, widths, and sizes of map elements for full basemap styling.
• Control styling by zoom level.
• Use custom fonts and icons.

Read the Custom Map Styles section to learn more about the advanced capabilities of the HERE Style Editor.

Map Downloader

In Navigate Edition, the MapDownloader class is a proper replacement of the Premium Edition NMAMapLoader class. The implementation of offline map support in an application starts from this MapDownloader class. Use the MapDownloader to explicitly preload the map data of a specific region or country. More information about map data download can be found in the Offline Maps section.

To Premium Edition users, the process of getting offline maps is known as active and passive downloading.

Active Downloading

With the Navigate Edition, the active downloading is made by an explicit execution of the available MapDownloader methods.

The part of countries or world map data, which can be downloaded is marked with a special region identificator. Use the getDownloadableRegions() method to get a list of regions with identificators. To get an overview:

1. Create the SDKNativeEngine first (if it is not already initialized) and then instantiate the MapDownloader using a static MapDownloader.fromEngineAsync(sdkNativeEngine) method call.
2. Download a list of available regions.
3. Explicitly call the downloadRegions() method with a list of regions IDs to start the active downloading of the map data.
4. After the downloadRegions method call you immediatelly get the instance which conforms to the MapDownloaderTask protocol and that can be used to cancel the request. The region data is downloaded asynchonously.
5. Implement the DownloadRegionsStatusListener protocol methods handlers to process the result.

Passive Downloading

Passive map downloading is done implicitly to update the map data and all contained information and it is performed by the HERE SDK itself on demand when a user changes the map scene (for example, when a user navigates using the map, performs pan or zoom in/out). This strategy requires a network connection at the moment of usage. Otherwise, only already downloaded and cached data will be displayed.

Places

With the Lite, Explore & Navigate Editions you can access almost the same backend services as with the Premium Edition. To get started, consult the Search section.

The Premium Edition users are familiar with NMAPlaces as initial point for different search requests(like NMADiscoveryRequest, NMAAutoSuggestionRequest,NMAPlaceRequest, NMAGeocodeRequest, NMAReverseGeocodeRequest, etc.) and listener concept for response.

Instead of creating separate request classes for search and explore use cases, the new HERE SDK combines all features into a SearchEngine(or OfflineSearchEngine). The SearchEngine has suggestions, geocoding and reverse geocoding and other advanced search features like search along a route. All these capabilities are based on remote HERE service data, which require Internet connection for making the request. The SearchEngine provides the latest fresh service data for each request. Read the Search Engine topic for more information.

With the SearchEngine you can initiate different asynchronous requests by calling the dedicated (overloaded) methods with different parameters. The parameters are grouped into structures with convenient naming (e.g. GeoCoordinates, TextQuery, CategoryQuery, AddressQuery, etc.). The search parameters define the search request type. All search requests immediatelly return TaskHandles, while response for the request is returned in completion block.

For example, to fetch places for a category, use the following overloaded search() method:

private func searchForCategories() {
    let categoryList = [PlaceCategory(id: PlaceCategory.eatAndDrink),
                        PlaceCategory(id: PlaceCategory.shoppingElectronics)]
    let categoryQuery = CategoryQuery(categoryList,
                                      areaCenter: GeoCoordinates(latitude: 52.520798,
                                                                 longitude: 13.409408))
    let searchOptions = SearchOptions(languageCode: LanguageCode.enUs,
                                      maxItems: 30)

    _ = searchEngine.search(categoryQuery: categoryQuery,
                            options: searchOptions,
                            completion: onSearchCompleted)
}

public func onSearchCompleted(error: SearchError?, items: [Place]?) {
    if let searchError = error {
        print("Search Error: \(searchError)")
        return
    }

    // If error is nil, it is guaranteed that the items will not be nil.
    showDialog(title: "Search Result", message: "\(items!.count) result(s) found. See log for details.")

    for place in items! {
        let addressText = place.address.addressText
        print(addressText)
    }
}

The Navigate Edition Place class is equivalent to Premium Edition NMAPlace class.

Connectivity Modes

The Premium Edition search functionality can be used in online and offline mode. The application developer has option to force offline request even if network connectivity is available. If connectivity parameter isn't set by developer then the online/offline mode control is performed on SDK side, based on the network connectivity.

In Navigate Edition the search functionality is controlled by two engines - SearchEngine and OfflineSearchEngine, what gives a flexibility in composition of components, required for specific application. The SearchEngine API methods have same interface as OfflineSearchEngine, but not vice versa.

The Navigate Edition SearchEngine is online version which have search, geocoding, reverse geocoding and suggesting capabilities. The OfflineSearchEngine uses the preloaded or cached map data for its local search, geocoding and reverse geocoding requests. The response might differ from online SearchEngine requests, because data freshness depends on latest downloaded map data.

Also you can implement the network-agnostic code wrappers as it is in Premium Edition. Follow the link for more offline search details and a Github example.

Note that place discovery requests that contain a list of links to additional places resources with detailed information about that place including ratings, images, reviews, editorials, and owner content are not yet supported.

Directions

The directions feature allows developers to define and display routes between a start and a destination point within their application. It supports many options such as road avoidance options and transport type for car, pedestrian and truck routing.

The Premium Edition functionality that uses the NMACoreRouter or NMAIsolineRouter should be migrated to the new RoutingEngine. Via the dedicated RoutingEngine you can access all available features. The Premium Edition routing mode parameters like NMATransportMode, NMARoutingOption and NMARoutingType in Navigate Edition are configured per transport type (e.g. CarOptions, TruckOptions, ScooterOptions, EVCarOptions, etc.). The below example shows how a route can be calculated with the new HERE SDK:

let carOptions = CarOptions()
routingEngine.calculateRoute(with: [Waypoint(coordinates: startGeoCoordinates!),
                                    Waypoint(coordinates: destinationGeoCoordinates!)],
                             carOptions: carOptions) { (routingError, routes) in

        if let error = routingError {
            self.showDialog(title: "Error while calculating a route:", message: "\(error)")
            return
        }

        let route = routes!.first
        // ...
}

The direction functionality can be implemented with help of RoutingEngine or OfflineRoutingEngine. The RoutingEngine is more precise as it uses network data with all traffic data updates, while OfflineRoutingEngine allows to calculate route when network is not available. The OfflineRoutingEngine uses loaded map data for its calculations. The map data load should be performed in advance before you have left the area with Internet connection, otherwise will return error.

The Navigate Edition introduced new route calculation dedicated for electric vehicles. It takes into account battery, energy consumption and reachability to charging station, to ensure that vehicle will not run out of energy. Another difference is in IsolineRouting calculations - the Navigate Edition extended range types with new consumptionInWattHours parameter. The Directions section provides an overview of the capabilities and how to calculate other type of routes with the new HERE SDK.

Turn-by-Turn Navigation for Walking and Driving

The Navigation Edition supports navigation on pedestrian, truck, and car routes. Using this feature, your app can check the current device position against a calculated route and get just-in-time navigational instructions. Both visual and audio instructions are supported. Currently, most visual information like road arrows must be added by the developer. For this you can use the icons available from the MSDKUI open source library.

The Premium Edition for turn-by-turn navigation and tracking functionality uses NMANavigationManager class. The NMANavigationManager relies on NMAPositioningManager, that produces coordinates updates behind the scenes. The simulation of navigation is made using dataSource of NMAPositioningManager:

• NMALoggedPositionSource is used to generate position updates from GPS data log file.
• NMARoutePositionSource for position from NMARoute geometry and stable movementSpeed.
• NMADevicePositionSource or nil for consuming real device position updates.

Example of position simulation for navigation in Premium Edition:

    // Simulation navigation by init the PositionSource with route and set movement speed
    let source = NMARoutePositionSource(route: route)
    source.movementSpeed = 60
    NMAPositioningManager.sharedInstance().dataSource = source

The Premium Edition example of turn-by-turn navigation using device position or simulation is available on Github.

In contrast to the Premium Edition, the Navigate Edition does not rely on a NMAPositioningManager running behind the scenes. Instead you are free to feed locations from any source into the Navigator: This class bundles all available guidance functionality. It is the equivalent to Premium's NMANavigationManager.

Once you have set a location source and a route, the Navigator will send events about the progress along the route. For example, to know when a waypoint is reached, set the receiving class as MilestoneReachedDelegate and use the following snippet:

// Conform to MilestoneReachedDelegate.
// Notifies when a waypoint on the route is reached.
func onMilestoneReached(_ milestone: Milestone) {
    if let waypointIndex = milestone.waypointIndex {
        print("A user-defined waypoint was reached, index of waypoint: \(waypointIndex)")
        print("Original coordinates: \(String(describing: milestone.originalCoordinates))")
    } else {
        // For example, when transport mode changes due to a ferry.
        print("A system defined waypoint was reached at \(milestone.mapMatchedCoordinates)")
    }
}

The Premium Edition users might find the Milestone term similar to Waypoint, but there is small difference - Waypoint is used for route creation, while Milestone is point on created route. Milestone can be added automatically between route sections where extra action is required(e.g. transport type change).

The Navigation Editon also supports a simulation mode. Instead of creating NMARoutePositionSource and set it to NMAPositioningManager instance you use a separate LocationSimulator to generate Location updates. This allows better decoupling from navigation and the various available location sources.

The code below creates a new instance and allows a Route and LocationSimulatorOptions as parameter. The latter allows to set the desired speed settings:

let locationSimulatorOptions = LocationSimulatorOptions(speedFactor: 10,
                                                        notificationIntervalInMilliseconds: 100)
let locationSimulator: LocationSimulator

do {
    try locationSimulator = LocationSimulator(route: route,
                                              options: locationSimulatorOptions)
} catch let instantiationError {
    fatalError("Failed to initialize LocationSimulator. Cause: \(instantiationError)")
}

By attaching a locationSimulator.delegate to the LocationSimulator you can get notified on Location updates. Then you can feed them separately into the Navigator. The LocationSimulator can be used for any route simulation purposes, also it supports playback of GPX log traces.

In Premium Edition the NMANavigationManager tracking functionality requires NMANavigationManager execution of startTracking method with specified NMATransportType(car, pedestrian, truck, etc.):

NMANavigationManager.sharedInstance().map = self.mapView;
let error = NMANavigationManager.sharedInstance().startTracking(.car)

In Navigate Edition with the dedicated Navigator class you can also track the current position and display it on the map without a calculated route. It's enough to reset route property to nil and ensure that position provider is not simulater.

The Premium Edition has built-in text-to-speech synthesizer and separate NMAVoicePackage for language, which can be downloaded and installed from NMAVoiceCatalog. When the package is configured the NMANavigationManager plays the speech output during navigation. In Navigate Edition the text-to-speech voice for navigation is controlled by user. The SDK has built-in languages for instructions generation.

1. Get list of available languages by executing Navigator.availableLanguagesForManeuverNotifications().
2. Set up maneuverNotificationOptions for Navigator with language that matches user needs and is available in SDK.
3. Ensure your instance conforms to ManeuverNotificationDelegate protocol and is set as maneuverNotificationDelegate for Navigator.

4. Add own text-to-speech handler for playing text received in onManeuverNotification delegate method.

5. To support text-to-speech voice navigation there is no separate VoiceCatalog download needed. For your convenience, these assets are now integrated into the HERE SDK library.

6. Note that traffic-aware routing is enabled by default and the current traffic delay can be retrieved from the RouteProgress event during turn-by-turn navigation.

A more detailed introduction to the various navigation features can be found in the Navigation section.

3D Venues

In comparison to the Premium Edition, you can only integrate private venues with the Navigate Edition. This can include shopping malls, airports, train stations and other buildings. You can search for a venue, opening a venue, and getting a notification when a venue is visible in the map viewport.

Public venues are already deprecated for the Premium Edition and they are not availble for the Navigate Edition. If you are a venue owner and want HERE to continue to maintain and surface your venue in our offerings, or those of our partners, contact us at venues.support@here.com.

Positioning

The Navigate Edition allows applications to choose from two different location sources. Similar to the feature available in the Premium Edition, you can use any native location information provided by the iOS platform.

Use the following method to convert CLLocation instances to the Location class consumed by the HERE SDK to cover the most common fields:

private func convertLocation(nativeLocation: CLLocation) -> Location {
    let geoCoordinates = GeoCoordinates(latitude: nativeLocation.coordinate.latitude,
                                        longitude: nativeLocation.coordinate.longitude,
                                        altitude: nativeLocation.altitude)
    var location = Location(coordinates: geoCoordinates,
                            timestamp: nativeLocation.timestamp)
    location.bearingInDegrees = nativeLocation.course < 0 ? nil : nativeLocation.course
    location.speedInMetersPerSecond = nativeLocation.speed < 0 ? nil : nativeLocation.speed
    location.horizontalAccuracyInMeters = nativeLocation.horizontalAccuracy < 0 ? nil : nativeLocation.horizontalAccuracy
    location.verticalAccuracyInMeters = nativeLocation.verticalAccuracy < 0 ? nil : nativeLocation.verticalAccuracy

    return location
}

Within the Navigate Edition features are handled via the dedicated LocationEngine. This class replaces the NMAPositioningManager as known from the Premium Edition.

The Premium Edition handles map matching NMAGeoCoordinates using NMAPositioningManager, while Navigate Edition receives MapMatchedCoordinates and MapMatchedLocation in RouteProgressDelegate and NavigableLocationDelegate methods of Navigator instance.

Another difference is in location simulation - Navigate Edition has dedicated LocationSimulator instead of Premium Edition's NMAPositioningManager with custom dataSource. More details available in Turn-by-Turn Navigation for Walking and Driving section.

The application developer, who uses Premium Edition, has to add Bluetooth permission in application .plist, even if indoor positioning is not used.

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This is needed for the indoor positioning feature</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This is needed for the Bluetooth-based indoor positioning feature</string>

The capabilities of the Navigate Edition are described in the Get Locations section. Note that offline network positioning as well as indoor positioning are not yet available.

Map Disk Cache

The new HERE SDK allows you to set the map disk cache to another location such as an SD Card via the SDKNativeEngine. This is described in the Key Concepts section.

Example Apps

Below you can find a side-by-side comparison of the available example apps.

Search, Geocoding and Reverse Geocoding

Map Features

Routing and Navigation

Other Example Apps