# Key Concepts

In the following use case sections, we will guide you through the most common usage scenarios and reveal tips and easy-to-understand guidelines to help you get the most out of the HERE SDK for Flutter.

## How to use this Guide?

You can read this guide in any order. All sections are independent from each other, making it easy to skip any section and to dive straight into the topics which you are most interested in.

• In the example section, you can find the example apps accompanying this user guide.
• If you are interested in building your first app showing a HERE map, take a look at the Get Started section to guide you through the first simple steps.

## Code Snippets

The shown code snippets cover best practice example code ready to be used for your own applications. However, for the sake of simplicity and to not shadow the educational approach of this guide, not all edge scenarios may be handled, especially when it comes to error handling or robust threading. In some cases, the obvious code is left out, but it can be found in the accompanying example apps that can be built and deployed instantly on any supported device with a set of valid HERE credentials.

### Design Principles

The accompanying example apps follow the same structure. As much as possible the HERE SDK example code is decoupled from the surrounding platform code. We hope this makes it easier to see the relevant parts of the shown APIs. Each example app follows the same entry point from which the HERE SDK is initialized. Since each app is focusing on a different aspect of the HERE SDK, that code can be found in a single class postfixed with "...Example.dart" in its class name. Most often this class gets a reference to a MapView to start its work.

Despite the popular phrase that "everything is a widget", the example code is kept free of most Flutter dependencies - instead it's mostly pure Dart code that shows how the HERE SDK can be used.

## Dispose Objects

All HERE SDK classes will be garbage collected by Flutter if the instance is no longer referenced or set to null.

For the SDKNativeEngine, which can be initialized automatically or programmatically, you can free resources by calling SDKNativeEngine.sharedInstance?.dispose(), for example, when the hosting widget's lifetime has ended. Calling dispose() will stop pending requests and close open files and databases that are still running on the main thread. After calling dispose() any related HERE SDK feature should no longer be used.

## Callbacks and Listeners

• The HERE SDK exposes callbacks for single event notification such as for search results.
• For reoccurring event notifications such as for gesture events, listeners are used. When multiple listeners can be set, then the method pattern add_x() and remove_x() is used as naming convention. If only one listener can be set at a time, the set_x() pattern is used that can be set to null to stop listening.

## Debug Logs

You can use the LogAppender interface to insert your own log class into the SDKNativeEngine. This way you can log HERE SDK messages for various predefined log levels even for release builds of your app.

When running an iOS simulator, you can obtain logs without running Xcode by executing the following command from the terminal:

xcrun simctl spawn booted log stream --level debug


### Dependency Management

Currently, dependency management, for example, via https://pub.dev/, is not yet supported. This means that the HERE SDK plugin must be copied locally to an application project as described in the Get Started section.

## Is the HERE SDK Thread Safe?

The HERE SDK is not guaranteed to be thread safe and it is recommended to make calls to the SDK from the main thread. Internally, the HERE SDK will offload most of its work to a background thread, but callbacks to your code will always occur on the main thread. In general, thread safety is the responsibility of the caller. For example, it is unsafe to reuse an engine on different threads unless your code is synchronized.

## Engines

The HERE SDK contains several modules - or engines as we call them - to execute specific tasks such as calculating a route with the RoutingEngine or requesting search results via the SearchEngine. There are many more engines you can use with the HERE SDK and you can read more about them in the dedicated chapters below. However, most engines share common concepts that makes it easier to use them. For example:

• All engines share similar interfaces, callbacks and error handling.
• It is possible to start multiple instances of an engine in parallel.
• An online connection is required.

Below you can find an overview of the most common engines in the HERE SDK:

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

## Android Permissions

The HERE SDK for Flutter automatically merges all required permissions to the AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />


### Note

These permissions are not sensitive and are immediately granted upon installation by the system - they are always needed, as the HERE SDK needs to have a working internet connection. It is not a requirement to handle these permissions and there are no HERE SDK specific requirements on how to handle permissions.

However, be aware that a user can deny any permission after installation via the device's app settings. You can use a convenience class to notify the user upon app launch like shown here. Note that Flutter itself does not provide any mechanism to handle permissions - and the accompanying Flutter example apps do not utilize any specific Android permission handling. If no internet connection is available, most HERE SDK services will indicate this with an appropriate error message.

### Note

For some HERE SDK features, like HERE Positioning, you need additional permissions. See the dedicated Find your Location section how to handle them.

## Initialize the HERE SDK

The HERE SDK is automatically initialized when Flutter registers the HERE SDK plugin for the first time at application start, but you can manually initialize the HERE SDK again. This allows to inject credentials programmatically - together with other initialization options.

On Android devices you can add native steps to add an entry to the AndroidManifest file to defer initialization. Note that this is not possible on iOS devices.

## Use SDKOptions to Set Programmatically HERE Credentials and Cache Path

All HERE SDK engines, except for SDKNativeEngine, can operate independently from each other and require HERE credentials to request data. The credentials can be set as shown in the Get Started guide - or programmatically. This can be useful, for example, to inject credentials at runtime from a web service.

By default, the HERE SDK is initialized automatically and it is reading the credentials from the Info.plist or AndroidManifest file. In addition, a default cache path is used for caching map data.

When you want to set the credentials programmatically, you need to create your own instance of the SDKNativeEngine, which can then be used to set or to change your HERE SDK credentials at runtime:

SdkContext.init(IsolateOrigin.main);

// Clear the cache occupied by a previous instance (if any).
await SDKNativeEngine.sharedInstance?.dispose();

SDKOptions sdkOptions = SDKOptions.withAccessKeySecretAndCachePath("YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET", "");

SDKNativeEngine sdkNativeEngine;
try {
sdkNativeEngine = SDKNativeEngine(sdkOptions);
SDKNativeEngine.sharedInstance = sdkNativeEngine;
} on InstantiationException {
// Handle exception.
}

try {
_searchEngine = SearchEngine();
} on InstantiationException {
// Handle exception.
}


This allows you to set a shared instance that will be used for all engines under the hood. Above, we initialize the SearchEngine as an example. Note that a shared instance is also required when you add a map view.

Make sure to call SdkContext.init(IsolateOrigin.main) only once during application life time, since it initializes the isolate and set-up other resources that are need to initialize the HERE SDK.

### Note

In addition, when setting credentials programmatically, keep the tags holding dummy values for id and secret in your AndroidManifest.xml and Info.plist file. Empty values will lead to an exception.

By setting an empty string as cache path when initializing SDKOptions, you keep the default cache path.

### Note

It is also possible to specify the cache path from the AndroidManifest file (in android folder of your app) or the Info.plist (in ios folder of your app). Consult the API Reference for the SDKNativeEngine to see an example.

Multiple SDKNativeEngine instances can’t have the same access key id and the cache path is ensured to be unique per access key id. After creating a new SDKNativeEngine, the access key id cannot be changed. Only the secret key can be changed afterwards.

In general, it should not be necessary to initialize the HERE SDK multiple times and only one sharedInstance can be set.

Make sure to init the SDKContext before creating a new SDKNativeEngine instance, like shown above. In addition, it is recommended to dispose() any previous instance - as at the time of running this code, Flutter may have already created an instance. For example, the above code snippet can be called in the main() method of your widget.

### Note

Since turn-by-turn navigation requires caching, a valid cache path should be set when manually creating a SDKNativeEngine.

Alternatively, in rare use cases it may be useful to set an individual SDKNativeEngine instance for each of the feature engines:

SearchEngine searchEngine = SearchEngine.withSdkEngine(sdkNativeEngine);


If you don't set your credentials programmatically, the HERE SDK will be initialized automatically using the values found in the manifest or plist. Either way, invalid credentials will not block execution until these credentials are used to authenticate your app when you start to use an engine to request data - or when you want to show a map view.

Tip: One option to keep credentials secure is to store them on a secure server and retrieve them by requests using SSL connections. Credentials stored in AndroidManifest or Info.plist are easy to unveil, a better option can be to use data protection mechanisms such as Keychain data protection.

For best practice, consider:

• To avoid keeping sensitive data in plain text.
• To transfer credentials using a secure communication channel.
• To store credentials using encryption such as device security and strong encryption ciphers.
• To add anti-tampering and anti-debugging code, so that a potential attacker cannot intercept data during dynamic runtime execution.
• Track the application usage to detect anomalies.

### Use Engines with or without a Map View

Engines do not need a map view to operate. Therefore it is possible to run an engine as a stand-alone, without any map view added to your application. This way, you can build an app solely around a specific engine. With or without a map view - the procedure to create a new engine is exactly the same:

try {
_searchEngine = SearchEngine();
} on InstantiationException {
// Handle exception.
}


When you use the default constructor to initialize an engine for a stand-alone usage, the HERE SDK will use a shared SDKNativeEngine under the hood to take the credentials as found in the AndroidManifest or plist file. Alternatively, you can provide the credentials programmatically as shown in the previous section.

## Maps

One of the core features of the HERE SDK for iOS is Mapping, which includes adding a map view, changing the location displayed by the map, and modifying its properties. The primary component of the mapping API is the map view, which is integrated as a UIView subclass. The map view represents a vector based view to display a map and various properties.

HERE map data is updated on a weekly basis to ensure you always get the freshest map data available. By integrating the map view you can automatically benefit from this.

### Note

To create a simple map application, please refer to the Get Started section.

To manipulate the map and its properties it's best to start looking at the Camera section. More features include:

• Map gestures to handle common map gestures and default map behaviors like pan or rotate.
• Map schemes to instantly switch default map styles such as satellite versus normal map layer. More on the available map schemes you can find below.
• Map items to place objects and shapes onto the map and interact with them.
• Custom map styles to load custom map schemes.

### Performance Optimization

By default, the MapView is rendered with 60 frames per second (FPS). Via mapView.frameRate the maximum frame rate can be adjusted - for example, to reduce CPU / GPU usage on low end devices. It is also possible to deactivate automatic render cycles by setting FPS to 0. Setting negative values has no effect. The value can be set individually per MapView instance - in case your app contains multiple MapView's.

Another option is to use custom map styles that contain less elements to render.

To shrink the size of the HERE SDK framework, unused fonts can be removed before shipping an application.

### Map Schemes

The HERE SDK supports five preconfigured map schemes:

• normalDay: A lossless scaleable vector base map for usage during daylight.
• normalNight: A lossless scaleable vector base map for usage during night.
• hybridDay: A day version of a hybrid scheme combining satellite imagery with vector street network, map labels and POI information.
• hybridNight: A night version of a hybrid scheme combining satellite imagery with vector street network, map labels and POI information.
• satellite: A bitmap based map showing satellite imagery for various zoom stages.

Note that it is also possible to fully customize your own map styles, except for the satellite imagery.

Use the following code snippet to load a map scheme:

MapScheme mapScheme = MapScheme.normalDay;

(MapError? error) {
if (error != null) {
print('Map scene not loaded. MapError: \${error.toString()}');
return;
}

// ...
});


It is recommended to use the day variants during day time when the surrounding light is brighter. The night variants are optimized for usage when there is less light. For example, an application may switch from day to night scheme when a driver is passing through a tunnel.

 MapScheme.normalDay MapScheme.normalNight MapScheme.hybridDay MapScheme.hybridNight

In addition, the HERE SDK offers a satellite scheme, that does not contain any labels:

The available map styles are optimized to easily add additional content and overlays onto the base map without visual interference. The map schemes are less colorful and support a clean and neutral tone to maximize readability even in case of color blindness:

• The street network is designed in gray scales and provides a hierarchy through brightness, contrast and widths.
• Colors are overall rather bright set up.
• Key colors are grey, blue, green, white.

## HERE Logo Watermark

When using the HERE SDK, it is required that the HERE logo is always visible on the map view. By default, the HERE logo is located at the bottom right corner of the map. However, you can easily customize its location to meet your app design by calling setWatermarkPosition() on your map view instance. It is recommended to change the default placement, only when it is required due to overlapping UI elements. Note for very small views: If both edges of the map are less than 250 density independent pixels in size, the watermark will be hidden automatically.

### Remove Unused Font Files

The HERE SDK contains fonts to render map labels for all supported languages. If you want to optimize the size of the overall app, you can remove selected fonts. For example, the font with Chinese, Japanese and Korean characters is around 1.7MB. To remove this font, open the HERE SDK plugin folder and remove the following files:

• style/fonts/DroidSansFallback.woff
• style/fonts/DroidSansFallback.license

When you remove a font, it is recommended to switch the map language to any other language than the removed font. At least one font needs to be left to see any map labels. Note that each time a label needs to be displayed in a language for a font that was removed an error message is logged - for each character that is missing.

## Map Language

You can customize the language that is used on the map to show labels for streets, cities and other map data. By default, the local language of a region is used.

Use the HereMapController to set a languageCode as primaryLanguage. This sets the language for the world - or set null to switch back to the default behavior. If a language is not supported in any region of the world, the local language for that region is shown instead.

## Availability of Map Data

By default, a few regions in the world including Japan, China and Korea, contain limited map data. To get access to the full map data, please get in contact with your HERE representative.

## Coverage

Consult the coverage page to get detailed information on supported countries and languages per feature.

## Map Caching

To better support online and offline use cases, the HERE SDK for Flutter supports caching of downloaded vector map data. This happens in the background. While interacting with the map, the data is stored locally on the device and can be accessed even when the device loses connection or operates in an offline mode.

The integrated map caching mechanism only supports the standard vector based map schemes - satellite images, for example, are not cached.

Please note that the amount of cached data is limited and will be overwritten with new map data while using the map. In most cases, this is sufficient to give the user the impression of a faster start-up time - as no additional data must be downloaded when you start an app again at the same location as before.

## Indoor Map

The HERE SDK provides the possibility to load, show and interact with private venues on the map. The HERE Indoor Map feature provides a wealth of hyperlocal information about indoor spaces, including building geometry and points of interest, spanning across multiple floors. HERE has mapped thousands of buildings globally, including, shopping malls, airports, train stations, parking garages, corporate campuses, factories, warehouses and many other types of buildings.