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.
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.
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.
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.
All HERE SDK classes that contain a
release() method will not be garbage collected if the instance is no longer referenced or set to null. Therefore, in case you need to clean up the memory, it is recommended to call
release() on all instances that are no longer needed for the rest of the lifetime of an app.
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
nullto stop listening.
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.
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.
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:
The HERE SDK for Flutter automatically merges all required permissions to the
<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
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.
Usually, engines 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, when using a map view in your app, the HERE SDK is initialized automatically and it is reading the credentials from the
AndroidManifest file. In addition, a default cache path is used for caching map data.
When you want to set the credentials programmatically, you must take care to initialize the HERE SDK yourself.
For this 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. This allows you to set a shared instance that will then be used for all engines under the hood. Note that a shared instance is also required when you add a map view.
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
AndroidManifestfile (in android folder of your app) or the
Info.plist(in ios folder of your app). Consult the API Reference for the
SDKNativeEngineto see an example.
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.
More usage examples and code snippets will follow soon.
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:
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.
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
Korean characters is around
1.7MB. To remove this font, open the HERE SDK plugin folder and remove the following files:
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.
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.
HereMapController to set a
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.
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.
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.