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.
Note: The HERE Map Service must be embedded with the application. For more information on this requirement, see Embedding the Map Service.

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. On the View menu, click Tool Windows > Project.
  2. A few tabs are available in this tool window. Select the Project tab to show a file system view of the application structure.
  3. Right-click on the app folder and select New > Directory to create a new folder. Use libs as the new folder name.
  4. In your operating system's file system, navigate to the extracted HERE SDK directory. Copy the HERE-sdk.aar file and paste it into the newly created libs directory.
  5. Optional: If you plan on extending this application with HERE Places, Custom Locations, 3D Venues, or Transit 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.
  6. Optional: To enable quick Javadoc reference within your Android Studio environment, scroll down to the External Libraries section, right-click on HERE-sdk, and then select Library Properties. Click the + button and locate HERE-sdk-javadoc.jar from the HERE SDK package.

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. Within the same <application></application> section in your AndroidManifest.xml file, add the following lines:
    <service
      android:name="com.here.android.mpa.service.MapService"
      android:label="HereMapService"
      android:process="global.Here.Map.Service.v2"
      android:exported="true" >
      <intent-filter>
        <action android:name="com.here.android.mpa.service.MapService" >
        </action>
      </intent-filter>
    </service>

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.

See the BasicMapSolution folder for a completed example. You need to add your own App_Id and App_Code for this completed example to work.

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.