HERE Android SDK Developer's Guide

Creating a Simple Application Using the HERE SDK

This tutorial provides instructions on how to create a simple application that uses the HERE Android SDK to render a map on an Android device.

This tutorial assumes that you are using the Android Studio development environment. Development tasks for this basic application include:
  • Acquire HERE credentials for accessing map services.
  • Create a new Android Studio project.
  • Add necessary resources, permissions, and a map fragment to the project.
  • Modify AndroidManifest.xml
  • Initialize the map fragment to create a map instance and associate this map with the map fragment for rendering on the client device.

Acquire HERE SDK Credentials

Typically, before developing a new HERE SDK application, you need to acquire a set of credentials by registering your application on http://developer.here.com. Each application requires a unique set of credentials. When you register your app, the registered bundle identifier must match the package name in your project.

Create a New Android Studio Project

The second stage of developing an application using the HERE SDK is to create a new project in Android Studio as follows:

  1. From the Welcome to Android Studio dialogue box, select New Project... to open the Create New Project dialog.
  2. In the New Android Application dialog, under Application name, specify an appropriate application name. The remainder of this tutorial uses BasicMapSolution as the application name.
  3. Under Company Domain, specify an appropriate domain.
  4. Edit the package name by clicking the Edit link. The remainder of this tutorial uses com.here.android.tutorial as the package name.
    Important: You must use the same package name as you have registered on developer.here.com. Failure to do so leads to a blank map to appear in your application.

    You can also edit this package name later in your AndroidManifest.xml:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.your.package.name.here"
      android:versionCode="1"
      android:versionName="1.0" >
    
    Figure 1. Edit the Package Name
  5. Under Project Location, specify an appropriate project location in the file system.
  6. Click Next.
  7. Select the form factors supported by your application. For the purpose of this tutorial, check Phone and Tablet.
  8. Under Minimum SDK, select the lowest version of the Android SDK you wish to support. For this sample application, use Android 4.0.3 "Ice Cream Sandwich".
  9. Click Next.
  10. You may be prompted to agree to a License Agreement. Click Accept, and then Next to install SDK components. After the installation is complete, click Next again.
  11. In the "Add an activity to Mobile" dialog box, select Empty Activity and click Next.
  12. In the "Customize Activity" dialog box, specify an appropriate activity name in Activity Name. This tutorial uses the name BasicMapActivity.
  13. Under Layout Name, specify an appropriate layout name. (This tutorial uses activity_main.)
  14. Click Finish.

Result: Andriod Studio creates the structure for your project and opens the development environment.

A few views are available in the Android Studio development environment. The Android view shows a flattened view of the application's structure, and the Project view shows a flattened view of the project's structure, including Gradle-related files.

The Android view provides quick access to key source files of your Android application. Selecting the activity_main.xml file in Android view opens the file in the Layout Editor and allows you to drag-and-drop widgets into your layout.

The following image shows how to switch between Android and Project view.

Figure 2. Switching Views in Android Studio

Add HERE SDK Libraries to Your Project

After creating the skeleton of your new application, add the HERE SDK resources as follows:

  1. From the directory where you installed the HERE SDK, copy the contents of the HERE-sdk/libs/ folder to your project's app/libs/ folder.
  2. Optional: Download the JTS Topology Suite (version 1.13 or later) from http://sourceforge.net/projects/jts-topo-suite/, extract its contents, and add the jts-*.jar library into the app/libs/ folder. The JTS library is required for rendering complex polygons.
  3. In your Android Studio project's app/libs/ folder, right-click the *.JAR files and select Add as Library..., then under the Add To module, select app and click OK.
  4. From the Android Studio Project View, click .idea > libraries, ensure HERE_sdk_javadoc.xml is not on the list. If it exists, delete HERE_sdk_javadoc.xml.
  5. Optional: If you plan on extending this application with HERE Places or Routing functionality, add the GSON library (release 2.2.4 or higher) to your project. You can add this library by clicking File > Project Structure. Next, select app from within the Modules grouping, and click on the Dependencies tab. You can then click the + button, select Library dependency, and look for the com.google.code.gson library.

Modify AndroidManifest.xml and Add HERE Credentials

  1. Add the HERE credentials to AndroidManifest.xml. For instructions on how to edit this file, see Authenticating Applications.
  2. Modify the opening <application> by adding the android:hardwareAccelerated="true" attribute.
    <application android:icon="@drawable/icon"
    android:label="@string/app_name" android:hardwareAccelerated="true">
  3. Add the following markup before the <application></application> tags:
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    Note: If your app uses Android API level 23 (Android 6.0) or above, you must also add code to request for permissions during runtime. You can find more information in the Request for Permissions section.
  4. Optional: To enable quick javadoc reference within your Android Studio environment, click on .idea/libraries/HERE_sdk.xml to edit it, and then add the following after </CLASSES> and before <SOURCES />:
    <JAVADOC>
      <root url="jar://$PROJECT_DIR$/app/libs/HERE-sdk-javadoc.jar!/" />
    </JAVADOC>
    

Result: Your project is able to make use of APIs from the HERE SDK.

Edit activity_main.xml

Along with permissions and credentials, you must add an Android <fragment /> tag to set up the map fragment that your application activity is associated with. In this section, we add a text label (generated as part of the default new application) and a map as follows:

  1. From the Android View, under the res/layout/ folder of your project, double-click the activity_main.xml file to open it for editing.
  2. Ensure that the XML file has <LinearLayout></LinearLayout> as its root element. Depending on your version of Android Studio, this may be a RelativeLayout instead. If that is the case, replace the contents of the file with the following:
    <LinearLayout
      xmlns:android="http://schemas.android.com/apk/res/android"
      xmlns:tools="http://schemas.android.com/tools"
      android:layout_width="fill_parent"
      android:layout_height="fill_parent"
      android:orientation="vertical" >
    
      <TextView
        android:id="@+id/title"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Hello World"
        tools:context=".BasicMapActivity" />
    
    </LinearLayout>
  3. Add the following markup beneath the <TextView/> tag:
    <!-- Map Fragment embedded with the map object -->
    <fragment
      class="com.here.android.mpa.mapping.MapFragment"
      android:id="@+id/mapfragment"
      android:layout_width="match_parent"
      android:layout_height="match_parent"/>

Result: When MapFragment is initialized, your application's BasicMapActivity contains a MapFragment UI element (with the ID mapfragment) that owns a Map object.

Initializing the Map Fragment

When you have defined the basic layout of the application and acquired necessary permissions, the final step is to initialize the instance of the MapFragment class, thus creating and associating a Map with the MapFragment declared in the activity_main.xml file:

  • From the Android View, double-click the BasicMapActivity.java file under the java folder to open it for editing.
  • Revise the import statements and functional logic of BasicMapActivity to look like the following:
    package com.here.android.tutorial;
    
    import android.app.Activity;
    import android.os.Bundle;
    
    import com.here.android.mpa.common.GeoCoordinate;
    import com.here.android.mpa.common.OnEngineInitListener;
    import com.here.android.mpa.mapping.Map;
    import com.here.android.mpa.mapping.MapFragment;
    
    public class BasicMapActivity extends Activity {
    
      // map embedded in the map fragment
      private Map map = null;
    
      // map fragment embedded in this activity
      private MapFragment mapFragment = null;
    
      @Override
      public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        initialize();
      }
    
      private void initialize() {
        setContentView(R.layout.activity_main);
    
        // Search for the map fragment to finish setup by calling init().
        mapFragment = (MapFragment)getFragmentManager().findFragmentById(
                R.id.mapfragment);
        mapFragment.init(new OnEngineInitListener() {
          @Override
          public void onEngineInitializationCompleted(
                  OnEngineInitListener.Error error)
          {
            if (error == OnEngineInitListener.Error.NONE) {
              // retrieve a reference of the map from the map fragment
              map = mapFragment.getMap();
              // Set the map center to the Vancouver region (no animation)
              map.setCenter(new GeoCoordinate(49.196261, -123.004773, 0.0),
                      Map.Animation.NONE);
              // Set the zoom level to the average between min and max
              map.setZoomLevel(
                (map.getMaxZoomLevel() + map.getMinZoomLevel()) / 2);
            } else {
              System.out.println("ERROR: Cannot initialize Map Fragment");
            }
          }
        });
      }
    }

Request for Permissions

If your app supports Android 6.0 or above, your app needs to ask users to grant certain permissions at runtime. For more information about this requirement, see Requesting Android Permissions.

Run the Applciation

You can run your simple application by pressing the key combination Shift + F10 (or Ctrl + R on Macs) from within Android Studio. The application renders a map retrieved from the HERE servers. When you are running your application on a device, make sure a data connection is enabled.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.