Update from previous versions

Keeping your HERE SDK up-to-date ensures you have the latest features, improvements, and map data. In order to benefit from the latest updates, integrate a newer HERE SDK version into your application and publish an update. For Navigate customers, this guide explains how to update to the latest map version automatically, and, if necessary, downgrade to a previous map version.

You can update to a newer HERE SDK version by replacing the HERE SDK AAR:

Get the latest HERE SDK release. To learn how, see Get started.
Copy the HERE SDK AAR file (*.aar) to your application's app/libs folder (as specified in the app's build.gradle file).
If you are using Android Studio, click the Sync button ("Sync Project with Gradle Files") to integrate the HERE SDK.
Adapt the source code of your application to the latest API changes, if needed.

Get the current HERE SDK version

Via SDKBuildInformation you can retrieve version of the currently integrated HERE SDK Android archive (AAR):

Log.d("HERE SDK version: ", SDKBuildInformation.sdkVersion().versionName);

Note that the HERE SDK version is automatically logged by the SDK.

Update automatically (only available for Navigate)

The HERE SDK version can only be updated by integrating a new HERE SDK release into your application.

Below, we demonstrate how to update the map version programmatically: it is possible to update the map version independently of the currently integrated HERE SDK version.

Note

The map version determines the data retrieved for both online and offline use. This data includes information relevant for map visualization, as well as data used for search, routing, and navigation. You can specify which data to retrieve by changing the default LayerConfiguration.

When an app update integrates a new HERE SDK version, it will likely feature a new map version as well. However, the map data will not be automatically updated.

Check the currently used map version by calling mapUpdater.getCurrentMapVersion().
Check if a map version update is available by calling mapUpdater.retrieveCatalogsUpdateInfo().

Can you automatically update to the latest map version, for example, at each application start?

Yes, this is possible when you have no installed regions. Please read on to see how this can be done.
If you have installed regions, you need to update via mapUpdater.updateCatalog(), see the Offline Maps section. If you have no installed regions, you are ready to go and you can update by setting a CatalogVersionHint.

When creating a CatalogConfiguration, you can set a CatalogVersionHint (see also above):

// We want to start with the latest catalog version.
boolean ignoreCachedData = true;
CatalogVersionHint versionHint = CatalogVersionHint.latest(ignoreCachedData);

In effect, this will auto-update the cached map data on each start when you initialize the HERE SDK. By default, you need to set the OCM identifier of the map (unless you use a custom map, see above):

String defaultOCMHRN = "hrn:here:data::olp-here:ocm";
DesiredCatalog defaultOCMCatalog = new DesiredCatalog(defaultOCMHRN, versionHint);
catalogConfigurations.add(new CatalogConfiguration(defaultOCMCatalog));

Note that this will disable incremental map updates when no patchHrn value is set: if you have installed regions, you need to update via mapUpdater.updateCatalog(), see the Offline Maps section. Incremental map updates are only applicable when you have installed regions.

As a next step, you can initialize the HERE SDK and set the catalogConfigurations via SDKOptions:

AuthenticationMode authenticationMode = AuthenticationMode.withKeySecret(accessKeyID, accessKeySecret);
SDKOptions options = new SDKOptions(authenticationMode);
options.catalogConfigurations = catalogConfigurations;

try {
    Context context = this;
    SDKNativeEngine.makeSharedInstance(context, options);
} catch (InstantiationErrorException e) {
    throw new RuntimeException("Initialization of HERE SDK failed: " + e.error.name());
}

Keep in mind that this code will not update the cached map data, if there are installed regions on a device. Cached data present on a device - for example, data in the map cache or data cached by PrefetchAroundLocation or PrefetchAroundRouteOnIntervals - will become obsolete if a newer map version is available. Such data will be evicted using a LRU strategy over time - which means, that the cache will not be deleted immediately, but when needed, then newer data will be used and old data will be evicted when the cache is full. Therefore, this has no or only a very limited effect on the start-up time.

In order to automatically update cached OCM-based map data, such as for the HERE SDK (Navigate), use the default HRN value: "hrn:here:data::olp-here:ocm" in your DesiredCatalog - as shown in the code snippet above.

With the flag ignoreCachedData you can specify how any cached data that may be present on a device should be treated when trying to update the map version. If set to false, the HERE SDK will auto-update to use the latest version only when there is no cached map data at all (for example, at first install or after clearing the cache) and no installed map data. Otherwise, this will have no effect.

Downgrade to a previous version (only avaialble for the Navigate)

You can also hard-select a map version: for example, if you want to start with a specific catalog version - even if it is older than the current one.

List<CatalogConfiguration> catalogConfigurations = new ArrayList<>();
CatalogVersionHint versionHint = CatalogVersionHint.specific(57);

After this, follow the same steps as shown in the previous section when initializing the HERE SDK.

Note that this has only an effect if there is no cached or persisted map data (that is installed regions). For example, you can clear the cache before leaving an app by calling:

SDKCache.fromEngine(SDKNativeEngine.getSharedInstance()).clearCache(error -> {
    if (error != null) {
        Log.d(TAG, "clearCache failed: " + error.name());
    }
});

For first-time installs this is not necessary - if you do this before showing a map view and before prefetching route data.

Note

Note that the HERE SDK does not allow to downgrade or to auto-update installed Region map data. With the MapUpdater it is only possible to update offline map data (and the cache) to the latest version.

Deprecations and beta versions

The team behind the HERE SDK is continuously reviewing and improving available APIs to provide both flexibility and ease of use, alongside consistent interfaces.

To ensure stable APIs across releases, we adhere to a deprecation process. Deprecated APIs are maintained for two major versions starting from the subsequent major release after their deprecation is announced in our changelog. This typically spans a period of six to nine months. You can always check the API Reference to see which versions are affected and when an interface was marked as deprecated. Note that updates to supported iOS, Android and Flutter versions are treated separately and will be announced in the changelog at least one major release in advance.

Some of our new and potentially unstable APIs are designated as beta in our API Reference. Beta releases do not follow a deprecation process unless otherwise specified. If you choose to use beta APIs, please note that they may contain bugs and exhibit unexpected behaviors.

For HERE backend services used by the HERE SDK, refer to the feature lifecycle policy.

We value your feedback and are always interested in hearing suggestions for further improvements.