Migration Guide

This guideline provides a set of steps to migrate from another HERE SDK edition to the HERE SDK for iOS (Navigate 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.

At a glance

• Within the Lite, Explore & Navigate Editions it is straight-forward to switch from one platform to another: All available platforms - Android, iOS and Flutter - share the same native code base under the hood. This way the available HERE SDK features behave consistently across platforms while being faithfully adapted to the individual platform conventions. Nevertheless, different features may result in different APIs and behavior - for example, the HERE Rendering Engine behaves different than the Lite Renderer and thus, the MapViewLite component contains slightly different APIs. More details on the main differences are shown below.

• The Starter and Premium Editions share a different technology stack. As a result, most APIs, concepts and behaviors differ from the new Lite, Explore & Navigate Editions. This may require a more coherent migration strategy. The possible steps are shown below. Note that the Starter Edition is deprecated.

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 with the Freemium plan. 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.

Note: For larger projects it may be feasible to create isolated projects that allow you to test your code with the new SDK in advance. This allows you to see if the new behavior matches your expectations - before all desired features are migrated.

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 featurewise instead of producing countless compile errors once a library is deintegrated.

Warning: It is not possible to integrate two different editions into the same app. Therefore, some classes may cause duplication errors at compile time.

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 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.

Note that the Navigate Edition also provides zoom levels, but the actual level of detail may differ. The map projection of the Navigate Edition uses globe projection instead of mercator projection. In addition, the Navigate Edition uses the distance to earth to position the camera above the map as this allows more precise results. To convert your existing Lite zoom level values to distance in meters, you can use the following nearing formula:

double distanceToEarthInMeters = Math.pow(2, 16.251628683 - zoomlevelFromLite);

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

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. 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's Guide to get a first overview of the available features and possible differences. 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.

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

Since the Starter Edition is deprecated, 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. Similar to the Explore Edition that replaces the Starter Edition, the Starter Edition can be seen as a subset of the Navigate Edition.

Note: Important

This migration guide does not provide a 1:1 comparison between the Premium Edition and the Navigate Edition due to the complexity and divergence of both editions. Instead, the focus lies on general concepts and patterns - as well as the differences - to provide a rough guideline to get started.

• In most cases, it may be easier to remove the old code completely and insert the new code from the Navigate Edition featurewise - instead of converting the code line-by-line.

• For this, the best approach may be to look for suitable code snippets you can take from the various use cases shown in this Developer's Guide or on GitHub. See also the possible Migration Strategies described above.

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 highly 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.

Feature Lists

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.

If a feature is not available for the Navigate Edition, consult your HERE representative. It may be already planned for one of the next regular releases.

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.

Note: These credentials are tied to the account used to obtain the credentials. This makes it possible to use the same set of credentials for multiple apps.

Artifactory Support

The Lite, Explore & Navigate Editions do not yet provide artifactory support. 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 Navigate Edition 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.

• SearchEngine: Includes all functionality to search for places, suggestions and locations including geocoding and reverse geocoding.
• RoutingEngine: Allows to calculate routes including various options and transport types.
• LocationEngine: An advanced HERE positioning solution.
• ConsentEngine: A supportive engine that helps to aggregate the user's consent before using, for example, the LocationEngine.
• VenueEngine: A specialized engine to support the integration of private venues into your apps.
• SDKNativeEngine: Normally not needed, but this engine allows to set credentials programmatically and allows a few other advanced settings.
• Navigator: Although not having 'engine' in its name, this class acts as an engine and controls all functionality around turn-by-turn navigation.

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

Map View

The Navigate Edition features 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.

• Consult the API Reference to see the available predefined MapScheme styles that are available for the Navigate Edition.

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

• 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.

Places

With the Navigation Edition you can access almost the same backend services as with the Premium Edition. To get started, consult the Search section.

Instead of creating separate request classes for search and explore use cases, the Navigate Edition combines all features into a single SearchEngine. This includes suggestions, geocoding and reverse geocoding and other advanced search features like search along a route. The equivalent NMAPlace class is simply called Place.

With the SearchEngine you can initiate different asynchronous requests by calling the dedicated (overloaded) methods. 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! {
}
}


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. Also, offline search is 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.

Via the dedicated RoutingEngine you can access all available features. The below example shows how a route can be calculated with the Navigate Edition:

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 Directions section provides an overview of the capabilities and how to calculate other type of routes with the Navigate Edition.

Note that the following features are not yet supported:

• Bicycle Routing
• Scooter Routing
• Transit Routing
• Indoor Venue Routing
• Offline Routing

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.

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.

With the dedicated Navigator class you can also track the current position and display it on the map without a calculated route.

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 Navigation Editon also supports a simulation mode. Instead of calling simulate(route, speedInMetersPerSecond) on the NMANavigationManager 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,
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. This also makes Premium's PositionSimulator obsolete: Instead, use the LocationSimulator for any route simulation purposes. The LocationSimulator also supports playback of GPX log traces.

• 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.

• 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 basic positioning feature available for 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 advanced positioning features are handled via the dedicated LocationEngine. This class replaces the NMAPositioningManager as known from the Premium Edition.

The advanced positioning 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 Navigate Edition 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.

Missing Features

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

• LiveSight
• Fleet Telematics / Custom Routes
• Platform Data Extensions
• Toll Cost Extensions