Update from previous versions

Keeping your HERE SDK up-to-date ensures you have the latest features, improvements, and map data.

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

1. Get the latest HERE SDK release. To learn more, see Get started.
2. Unzip the downloaded HERE SDK for Flutter TAR package, then rename the folder to here_sdk.
3. Copy the renamed plugin folder to the plugins folder inside your project. With this, the content of the plugin folder is contained in your_app/plugins/here_sdk.
4. Execute flutter pub get (or clicked the respective "Pub get" button in Android Studio or any other IDE).
5. Adapt the source code of your application to the latest API changes, if needed.

Find more information on integrating a HERE SDK release in our Get started guide.

Get current HERE SDK version

Via SDKBuildInformation you can retrieve version of the currently integrated HERE SDK plugin:

print("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):

bool ignoreCachedData = true;
CatalogVersionHint versionHint = CatalogVersionHint.latestWithIgnoringCachedData(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):

final 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 sdkOptions = SDKOptions.withAuthenticationMode(authenticationMode);
sdkOptions.catalogConfigurations = catalogConfigurations

try {
  await SDKNativeEngine.makeSharedInstance(sdkOptions);
} on InstantiationException {
  throw Exception("Failed to initialize the HERE SDK.");
}

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 available for 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 = [];
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 clearCache() on the SDKCache instance (see below).

SDKCache.fromSdkEngine(SDKNativeEngine.sharedInstance!).clearAppCache((error) {
  if (error != null) {
    print("clearCache failed: " + error.toString());
  }
});

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.