Migration Guide

This guideline provides a set of steps to migrate from another HERE SDK edition to the HERE SDK for Android (Navigate Edition). It applies also for users of the Explore Edition, but please 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 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 library first.

2. Then integrate the new SDK library 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.

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 library inside the app's libs folder and insert your new credentials into the AndroidManifest.xml. 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. Adapt the namespace in your XML layoutfile:

Replace

<com.here.sdk.mapviewlite.MapViewLite
   android:id="@+id/map_view"
   android:layout_width="match_parent"
   android:layout_height="match_parent">
</com.here.sdk.mapviewlite.MapViewLite>

with

<com.here.sdk.mapview.MapView
   android:id="@+id/map_view"
   android:layout_width="match_parent"
   android:layout_height="match_parent">
</com.here.sdk.mapview.MapView>

1. Notice that the MapStyle schemes available for the Lite Edition are replaced by MapScheme styles. The NORMAL_DAY 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.

2. See that 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.

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

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

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.

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
• Natural guidance
• Bus navigation
• School zone warner
• Dynamic penalty support in routing
• Signposts
• Highway junction views
• Autozoom in visual navigator
• Environmental zone rendering
• Cluster marker theming
• Polyline styling: dots
• Location indicator with accuracy
• Incremental map updater
• Route eat-up

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.
• Custom location extension: This feature is already replaced with "bring your own data" for search and geocoding. With the newly introduced 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 will be replaced by a new custom data concept to support the "bring your own data" use case, similar as for search and geocoding with MyPlaces (see above).
• Platform data extension: This feature is planned to be replaced by the new Map Attributes service later in 2022. Until then, this API can be used directly via the available REST API - if needed earlier.

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.

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 library (AAR) 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.

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

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.

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.

• 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 DOUBLE_TAP and TWO_FINGER_TAP gestures:

mapView.getGestures().disableDefaultAction(GestureType.DOUBLE_TAP);
mapView.getGestures().disableDefaultAction(GestureType.TWO_FINGER_TAP);

mapView.getGestures().setDoubleTapListener(new DoubleTapListener() {
    @Override
    public void onDoubleTap(@NonNull Point2D touchPoint) {
        // Start your custom zoom in animation.
    }
});

mapView.getGestures().setTwoFingerTapListener(new TwoFingerTapListener() {
    @Override
    public void onTwoFingerTap(@NonNull Point2D touchCenterPoint) {
        // Start your custom zoom out animation.
    }
});

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

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.

Instead of using separate request classes like SearchRequest or ExploreRequest, the new HERE SDK combines all features into a single SearchEngine. This includes suggestions, geocoding and reverse geocoding and other advanced search features like search along a route.

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 void searchForCategories() {
    List<PlaceCategory> categoryList = new ArrayList<>();
    categoryList.add(new PlaceCategory(PlaceCategory.EAT_AND_DRINK));
    categoryList.add(new PlaceCategory(PlaceCategory.SHOPPING_ELECTRONICS));
    CategoryQuery categoryQuery = new CategoryQuery(categoryList, new GeoCoordinates(52.520798, 13.409408));

    SearchOptions searchOptions = new SearchOptions();

    searchEngine.search(categoryQuery, searchOptions, new SearchCallback() {
        @Override
        public void onSearchCompleted(SearchError searchError, List<Place> list) {
            if (searchError != null) {
                // An error happened ...
                return;
            }

            // If error is null, list is guaranteed to be not empty.
            for (Place searchResult : list) {
                String addressText = searchResult.getAddress().addressText;
                Log.d(TAG, addressText);
            }
        }
    });
}

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.

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

Waypoint startWaypoint = new Waypoint(startGeoCoordinates);
Waypoint destinationWaypoint = new Waypoint(destinationGeoCoordinates);

List<Waypoint> waypoints =
        new ArrayList<>(Arrays.asList(startWaypoint, destinationWaypoint));

routingEngine.calculateRoute(
        waypoints,
        new CarOptions(),
        new CalculateRouteCallback() {
            @Override
            public void onRouteCalculated(@Nullable RoutingError routingError, @Nullable List<Route> routes) {
                if (routingError == null) {
                    Route route = routes.get(0);
                    // ...
                } else {
                    showDialog("Error while calculating a route:", routingError.toString());
                }
            }
        });

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.

In contrast to the Premium Edition, the Navigate Edition does not rely on a PositioningManager 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 NavigationManager.

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, use the following snippet:

navigator.setMilestoneReachedListener(new MilestoneReachedListener() {
    @Override
    public void onMilestoneReached(Milestone milestone) {
        if (milestone.waypointIndex != null) {
            Log.d(TAG, "A user-defined waypoint was reached, index of waypoint: " + milestone.waypointIndex);
            Log.d(TAG,"Original coordinates: " + milestone.originalCoordinates);
        } else {
            // For example, when transport mode changes due to a ferry.
            Log.d(TAG,"A system defined waypoint was reached at " + milestone.mapMatchedCoordinates);
        }
    }
});

The Navigation Editon also supports a simulation mode. Instead of calling navigationManager.simulate(route, speedInMetersPerSecond); 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:

LocationSimulator locationSimulator;

try {
    locationSimulator = new LocationSimulator(route, locationSimulatorOptions);
} catch (InstantiationErrorException e) {
    throw new RuntimeException("Initialization of LocationSimulator failed: " + e.error.name());
}

By attaching a LocationListener 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, open a venue, and get 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 Android platform.

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

private Location convertLocation(android.location.Location nativeLocation) {
    GeoCoordinates geoCoordinates = new GeoCoordinates(
            nativeLocation.getLatitude(),
            nativeLocation.getLongitude(),
            nativeLocation.getAltitude());

    Location location = new Location(geoCoordinates, new Date());

    if (nativeLocation.hasBearing()) {
        location.bearingInDegrees = (double) nativeLocation.getBearing();
    }

    if (nativeLocation.hasSpeed()) {
        location.speedInMetersPerSecond = (double) nativeLocation.getSpeed();
    }

    if (nativeLocation.hasAccuracy()) {
        location.horizontalAccuracyInMeters = (double) nativeLocation.getAccuracy();
    }

    return location;
}

Within the Navigate Edition advanced positioning features are handled via the dedicated LocationEngine. This class replaces the PositioningManager 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 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