Get Started
This guide walks you through the first steps to build apps with the HERE SDK. The HERE SDK is tailored to bring the best and freshest assets from the HERE platform to your mobile applications.
Before you begin, make sure you have read the following:
In order to start development, you need to get the HERE SDK package:
Note
Please contact us to receive access including a set of evaluation credentials. For now, the Navigate Edition is only available upon request. The HERE SDK package for the Navigate Edition is available on the HERE platform portal. Make sure you have access, then:
- On the platform portal browse to the Navigate Edition. Choose the Android platform.
- Click the Get Now button. Note that the package will download in the background. Be patient, it may take a while.
- Unzip the package. It includes the Android Archive (AAR) (the HERE SDK binary to include in your app(s)), a set of example apps, this documentation and some more useful files.
Get Your Credentials
The HERE SDK for Android requires two strings to authenticate your app:
- ACCESS KEY ID: A unique ID for your account.
- ACCESS KEY SECRET: A secret key, which is shown only once after creation time. Please make sure to note it down before leaving developer.here.com.
No other credentials or tokens are needed to use the HERE SDK. You can register and manage your app as described in the Identity & Access Management guide.
Note
Note that these credentials can be reused for the Lite and Explore Editions regardless of the platform - furthermore, you can use these credentials for more than one app. For example, they will work with all example apps you can find on GitHub. For the Navigate Edition you need to contact your HERE representative to generate a set of evaluation credentials.
When you obtain your credentials, also an APP ID is generated. This ID is not consumed by the HERE SDK, but it is recommended to mention it when contacting the HERE support team.
To obtain your personal ACCESS KEY ID (access_key_id
) and ACCESS KEY SECRET (access_key_secret
), do the following:
Note
Please contact your HERE representative to receive access including a set of evaluation credentials. For now, the Navigate Edition is only available upon request.
See also the below section Authenticating Applications to learn more details on how to set the credentials for an app.
Try the Example Apps
The easiest way to get started, is to try one of the many example projects that are available for the HERE SDK.
Choose an example of your choice, then:
- Add the HERE SDK framework to the app's
libs
folder. - Add your HERE credentials (
access_key_id
and access_key_secret
) to the AndroidManifest.xml
file.
Now you are ready to open the project with Android Studio and you can instantly execute the app on your device or simulator.
Note
Did you know that almost every topic of this Developer's Guide is available as executable app?
Feel free to experiment with the code of the examples. You can also follow the below guide to get a more thorough introduction on how to develop apps with the HERE SDK.
Create a New Android Project
As a very first step-by-step example, we will develop a "Hello Map" Android application that shows - yes! - a map. If you want to integrate the SDK into an existing application, you can skip this step. No specific SDK code is involved here. We recommend using Android Studio as the IDE. If you are new to Android development, please follow the guides on developer.android.com to help you get started with the first steps.
Note
The example code for "HelloMap" is available from here.
Start Android Studio (for this guide, we have used version Arctic Fox | 2020.3.1 Patch 3) and create a new project by selecting:
- Start a new Android Studio Project.
- Choose Phone and Tablet, select Empty Activity and click Next.
- Provide a project name, e.g. "HelloMap" and select Java or Kotlin as the language. For the example below, we have chosen Java.
- Next to "Minimum API level", set API 21 as the minimum Android SDK.
- Make sure an appropriate directory is chosen in "Save location" and click Finish to continue.
We recommend to use AndroidX support libaries. If not done already, in Android Studio click Refactor -> Migrate to AndroidX.
Once the wizard finishes, make sure to build the plain project and execute it on an emulator (or on a device). If all goes well, you should see the "Hello World" text.
Say Hello Map!
Once we have a working Android application, it's time to include the HERE SDK and to show a map on your emulator or device. Here's an overview of the next steps:
- Adapt your gradle script to integrate the HERE SDK.
- Set required credentials and permissions to your manifest file.
- Add a map view to your main activity's layout file.
- Add the code to load your first map scene.
Note: While all of the functionalities of the HERE SDK are accessible from the emulator, usage of a real device is strongly recommended. The overall performance will be better, and some features like gestures are just easier to use on multi-touch enabled hardware. The rendering of the map view is optimized for mobile device GPUs.
Let's begin with the first step to see how we can add the HERE SDK to our project.
Integrate the HERE SDK
On developer.here.com you can find the latest release artifacts including the HERE SDK framework archive to include in your application (named xx.yy.zz.release_date).
Copy the HERE SDK AAR file (*.aar) to your application's app/libs
folder.
Since the HERE SDK encourages the use of Lambda expressions, Java 8 or newer is required. Add the following inside the android
closure of the app level's build.gradle
file to desugar the output of the javac
compiler:
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
Note that this is usually added by default when you create a new Android Studio project. If it is not added, please add it manually.
Then extend the dependencies closure in the same build.gradle
file to make sure *.aar
files are included, by adding the following:
implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
Note
Note that this guide is based on HERE SDK version 4.9.4.0. If your AAR version is different from the version used for this guide, the steps may vary and you may need to adapt the source code of your app.
Now it's time to click the Sync
button ("Sync Project with Gradle Files") to integrate the SDK.
Set Your HERE Credentials
When using the HERE SDK, your application must be authenticated with a set of credentials you add to the AndroidManifest.xml
file of your project.
Once you have your credentials at hand, add your set of credentials inside the application
element in AndroidManifest.xml
:
<meta-data android:name="com.here.sdk.access_key_id" android:value="YOUR_ACCESS_KEY_ID" />
<meta-data android:name="com.here.sdk.access_key_secret" android:value="YOUR_ACCESS_KEY_SECRET" />
Note: The credentials are not tied to the package name or the application ID of your app, but to the account used to obtain the credentials. This makes it possible to use the same set of credentials for multiple apps.
Tip: Alternatively, you can set your credentials programmatically, for example, if you don't want to hardcode your credentials in the manifest for security reasons.
Handle Android Permissions
The HERE SDK for Android 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" />
Optionally, in AndroidManifest.xml
, you can add inside the top-level manifest
element the above permissions to be explicit about the requirements.
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, a user can deny any permission after installation via the device's app settings. Therefore it is recommended to add permission handling to your app to notify the user upon app launch.
The accompanying example apps show how this can be done utilizing a convenience class to keep you away from the boiler plate code. Of course, you can handle the permissions for your own application in a different way - or even decide to omit it: Note that 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.
Add the Map View
Now that we have the SDK integrated into the project and added the required permissions and credentials, we can add a new MapView
instance.
Note
The map view of the Explore Edition is rendered with the HERE Rendering Engine. A special light-weighted rendering architecture that is optimized for resource-constrained devices is available as part of the Lite Edition.
Open the layout file of the MainActivity
(usually named activity_main.xml
) and remove the "Hello World" TextView
(assuming you followed Android Studio's wizard). By default, it created a ConstraintLayout
where we can place the map view. Any other layout parent will suit too. Add the following piece of code:
<com.here.sdk.mapview.MapView
android:id="@+id/map_view"
android:layout_width="match_parent"
android:layout_height="match_parent">
</com.here.sdk.mapview.MapView>
A ConstraintLayout
has the advantage that it offers a flat view hierarchy and it works well with Android Studio's Layout Editor, but this is all up to you. The SDK's MapView
behaves exactly as you would expect from any other Android View
.
Apparently, we create the map view from our layout file. We need to also initialize it; to do this, update the onCreate()
method in your MainActivity
(or any other Activity
where you want to show a map view) so that it looks like the following:
private MapView mapView;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
mapView = findViewById(R.id.map_view);
mapView.onCreate(savedInstanceState);
}
You will get an error about MapView
being an unresolved symbol, so use the auto completion hotkey to add com.here.sdk.mapview.MapView
to your imports list, or add it manually.
Note: It is important to call mapView.onCreate()
to perform additional initialization tasks. Otherwise the map will not be rendered. Note that multiple MapView
instances can be created and rendered together on one screen as part of the same layout.
Knowning When the Map is Ready
The HERE Rendering Engine will be attached each time after onResume()
is called. The OnReadyListener
tells you once this happens:
mapView.setOnReadyListener(new MapView.OnReadyListener() {
@Override
public void onMapViewReady() {
Log.d(TAG, "HERE Rendering Engine attached.");
}
});
Most often, you may not need to wait for this event. For example, map items can be added any time. Once the HERE Rendering Engine
is attached, the map will become visible. Only code - such as picking map items from the map view - that requires map data should wait for this event to ensure that you will get the expected results.
Load a Map Scene
Before we can see any map on the device's screen, we need to decide how the map data should be rendered. Therefore, we need to asynchronously load a scene that allows us to customize the look of the map. When we load a scene, it will use one of the default map styles the SDK is shipped with.
Loading a map scene can be done from your MainActivity
class by adding few lines of code. For example, add the following method and call it when the activity has been created and all requested Android permissions are granted:
private void loadMapScene() {
mapView.getMapScene().loadScene(MapScheme.NORMAL_DAY, new MapScene.LoadSceneCallback() {
@Override
public void onLoadScene(@Nullable MapError mapError) {
if (mapError == null) {
double distanceInMeters = 1000 * 10;
mapView.getCamera().lookAt(
new GeoCoordinates(52.530932, 13.384915), distanceInMeters);
} else {
Log.d(TAG, "Loading map failed: mapError: " + mapError.name());
}
}
});
}
Again, as in onCreate()
, you will have to resolve the unresolved packages after adding the above code.
Call loadMapScene()
from within onCreate()
- or like shown in the example apps - once the Android permissions are granted:
...
loadMapScene();
...
Note
In the example's source code, you can find a convenience class called PermissionsRequestor
to keep you away from the boiler plate code that is needed for Android permission handling. As already mentioned above, you may want to handle the permissions for your own application in a different way. There are no HERE SDK specific requirements on how to handle permissions. Most example apps do not require special permissions, so permission handling is not mandatory, but considered a good habit.
As for most callbacks available in the HERE SDK, onLoadScene()
is called on the main thread when loading the scene is done. If MapError
is not null, it will indicate what went wrong.
Note
Since loading a scene is done asynchronously, you may get an OPERATION_IN_PROGRESS
error for a second call. Depending on your implementation, this may happen after quick screen orientation changes. In such a case, you do not need to call onLoadScene()
again - once a map scene is loaded, the existing map scheme can continue to be used, even if the Activity
is recreated due to a device rotation. However, any content that is added to the MapView
, such as MapMarker
items, needs to be added again after a screen orientation change.
From the MapView
, we can then access the Camera
to set some custom map parameters like the location we want the map centered on, and a zoom level which is specified by the camera's distance to earth. You can configure the Camera
as soon as you have a MapView
instance available. However, you will see the changes only taking effect after onLoadScene()
has finished. In general, it is recommended to wait with map manipulations until the scene has loaded. For example, camera operations may be enqueued until the scene is loaded, while other operations simply may have no effect without a map scene.
As an exercise, you can try to replace the above map style with the following: MapScheme.SATELLITE
. What do you get? Try out also other map schemes, like the normal night scheme.
Lastly, make sure to clean up when the activity lifetime ends: The HERE SDK for Android provides the mapView.onDestroy()
method to safely release all of its remaining resources. Additionally, it is recommended to pause rendering the map view when the Activity
is paused:
@Override
protected void onPause() {
super.onPause();
mapView.onPause();
}
@Override
protected void onResume() {
super.onResume();
mapView.onResume();
}
@Override
protected void onDestroy() {
super.onDestroy();
mapView.onDestroy();
}
Now it's time to build and run the app. If all goes well, you should see a HERE map covering the whole area of the view. Congratulations, you have just mastered your first steps in using the HERE SDK for Android. Thank you!
Screenshot: Showing main map scheme.
Screenshot: Showing satellite map scheme.
Info
Tip: Usually, the HERE SDK is initialized together with the map view. In the Key Concepts section you can find several ways to initialize the HERE SDK manually. This can help to speed-up loading time of the map view - as by default, the HERE SDK is initialized automatically when a map view is shown.
Video Tutorials
Follow the HERE team in a live coding series recorded for Twitch and now available on YouTube:
Watch us coding with the HERE SDK on YouTube!
The following live coding topics are available:
Troubleshooting
When you run into trouble, please make sure to first check the minimum requirements and the supported devices.
- I see only a blank white map: Make sure that your HERE credentials are valid and set as described in the Get Started section above. Also, make sure that your device is able to make an internet connection. With slower internet connections, it may take a while until you see the first map tiles loaded.
- In the logs I see "No map content will be displayed until valid config is provided.": Make sure that your code is really calling
loadScene()
. - The app crashes and in the logs I see "CL_magma - Couldn't load the default shader.": Your device must support OpenGL ES 3.0. If you are running a simulator, edit your emulator settings via Settings -> Advanced -> OpenGL ES API level. If it is set to "Autoselect", try to change it to "Renderer Maximum". This happens mostly on Windows machines.
- I am unable to resolve dependency for ':app@debug/compileClasspath': Could not find :heresdk-YOUR_SDK_VERSION: Make sure that your HERE SDK AAR matches the name in your application's build gradle file. Note: This is only needed, if you reference the version explicitly. If you follow the steps above, you don't have to do that as we use
*.aar
as wildcard to match any version. - I get the error "License for package Android SDK Platform not accepted." or similar: Make sure you have accepted all Android licenses, for example by installing the required tools and clicking the license button or by calling
cd /d "%ANDROID_SDK_ROOT%/tools/bin"
and sdkmanager --licenses
from your terminal. - I am seeing the following in a crash log: "Exception was thrown in Java and it was not handled.": The HERE SDK cannot handle runtime exceptions that are thrown on app side inside a callback. In such a case you will see this error log. It means that your code throws an exception in one of the HERE SDK callbacks that are handled by your application.
Need Help?
If you need assistance with this or any other HERE product, select one of the following options.
- If you have a HERE representative, contact them when you have questions/issues.
- If you manage your applications and accounts through developer.here.com, log into your account and check the pages on the SLA report.
- If you have more questions, please check stackoverflow.com/questions/tagged/here-api.
- If you have questions about billing, your account, or anything else Contact Us.
- If you have purchased your plan/product from a HERE reseller, contact your reseller.