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

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.

Conventions

For this guide, we preferably avoid the use of lambda notations to show the full type of information and other details, such as callback or listener name. Since Android Studio supports one-click conversion between anonymous classes and lambdas, adapting the examples to suit your personal preference should be simple.

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.

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.

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 execute their tasks asynchronously and receive their results on the main thread.
  • 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.

Set HERE Credentials from Manifest or Programmatically

Usually, engines can operate independently from each other and require HERE credentials to request data. The credentials can be set in the AndroidManifest file 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 manifest. In addition, a default cache path is used for caching map data.

Use SDKOptions to set HERE Credentials and Cache Path

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:

SDKOptions sdkOptions = new SDKOptions("YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET", context.getCacheDir().getPath());
SDKNativeEngine sdkNativeEngine = new SDKNativeEngine(sdkOptions);
SDKNativeEngine.setSharedInstance(sdkNativeEngine);

try {
    SearchEngine searchEngine = new SearchEngine();
    // ...
} catch (InstantiationErrorException e) {
    // 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.

Alternatively, you can set the engine individually for each engine:

SearchEngine searchEngine = new SearchEngine(sdkNativeEngine);

By default, the InitProvider of the HERE SDK will still look for the credentials in your AndroidManifest file. Therefore, when setting credentials programmatically, keep the tags holding dummy values for id and secret, like shown in the snippet below. Empty values will lead to an exception:

<meta-data android:name="com.here.sdk.access_key_id" android:value="cdefgabc" />
<meta-data android:name="com.here.sdk.access_key_secret" android:value="cdefgabc" />

Alternatively, call InitProvider.initialize() to avoid that the SDKInitializer will look into the AndroidManifest file - this procedure is described in the next section.

Manually Initialize the HERE SDK

When you want to set credentials programmatically and you want to avoid keeping meta-data tags in the manifest (see above), you can disable the HERE SDK's InitProvider and manually initialize the HERE SDK.

The InitProvider is responsible for the initialization of the HERE SDK and it reads the credentials from the manifest file. If it cannot find the <meta-data>-tag that is supposed to hold the credentials, it will throw a MetaDataNotFoundException.

To disable the InitProvider, add a new <provider> tag to the app's manifest nested under the <application>-tag. As name/authorities, specify the InitProvider. Disable it by setting tools:node="remove":

<provider
    android:name="com.here.sdk.engine.InitProvider"
    android:authorities="com.here.sdk.engine.InitProvider"
    android:exported="false"
    tools:node="remove" />

For this, you also need to bind the tools namespace declaration to the manifest tag as follows:

<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.your_domain.your_app">

Finally, after the InitProvider has been disabled, you need to call InitProvider.initialize(appContext) to initialize the required platform modules. Make sure to call this before creating the SDKNativeEngine - and before setting the content view holding your map view (if your app contains a map view):

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Manually initialize the HERE SDK.
    InitProvider.initialize(this);

    // Set credentials programmatically.
    SDKOptions sdkOptions = new SDKOptions("YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET", context.getCacheDir().getPath());
    SDKNativeEngine sdkNativeEngine = new SDKNativeEngine(sdkOptions);
    SDKNativeEngine.setSharedInstance(sdkNativeEngine);

    setContentView(R.layout.activity_main);

    // Get a MapView instance from the layout.
    mapView = findViewById(R.id.map_view);
    mapView.onCreate(savedInstanceState);

    // Handle required Android permissions ...
}

This way, you can manually initialize the HERE SDK and avoid setting dummy credentials in your manifest file.

If you don't set your credentials programmatically, the HERE SDK will be initialized automatically using the values found in the manifest. 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.

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 = new SearchEngine();
} catch (InstantiationErrorException e) {
    // 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 file. Alternatively, you can provide the credentials programmatically as shown in the previous section.

It is not possible to initialize an engine during the Application's onCreate() lifecycle. Any other point in time is fine. For example, a good place to initialize an engine may be in an Activity's onCreate()-method.

Remove Unnecessary Android Permissions

Applications may require less permissions based on the features they use. For example, if you don't include a map view, the following two permissions can be left out:

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

For an introduction to permission handling, check the Quick Start guide. All required permissions are automatically added by the HERE SDK to the manifest. It is recommended to always ask the user for permissions, even if they are already granted by the system. But what can be done if you want to remove unnecessary permissions?

The HERE SDK uses Android's manifest merger tool to combine all required permissions. This can be changed if needed. Edit your AndroidManifest.xml and add the attribute tools:node to remove the undesired permissions:

<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.xyz.abc">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <!-- The following two permissions are not needed when no map view is included. -->
    <uses-permission
      android:name="android.permission.READ_EXTERNAL_STORAGE"
      tools:node="remove" />
    <uses-permission
      android:name="android.permission.WRITE_EXTERNAL_STORAGE"
      tools:node="remove" />
    ...
</manifest>

Make sure to add the xmlns:tools namespace to your manifest tag. If you don't add explicit permission handling, the above may not be needed, unless your app requires other critical permissions.

The INTERNET and ACCESS_NETWORK_STATE permission are immediately granted upon installation by the system - but a user can deny access at any time after installation. If you want to notify the user upon the next app launch that internet access was turned off, you need to add permission handling as explained in the Quick Start guide. This would also prompt the user to grant the above two storage permissions. In such a case, therefore, it may be desirable to remove unnecessary permissions as shown above.

Maps

One of the core features of the HERE SDK for Android 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 View 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. While the map is vector based, you can also integrate custom map tiles from other providers.

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

To manipulate the map and its properties, it is 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.
  • Map items to place objects and shapes onto the map and interact with them.
  • Custom raster tiles to show custom server images as an additional map layer.
  • Custom map styles to fully customize the look of the existing map schemes.

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.

Map Caching

To better support online and offline use cases, the HERE SDK for Android 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.

results matching ""

    No results matching ""