Create a Simple App Using HERE SDK

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 https://developer.here.com. Each application requires a unique set of credentials. When you register your app, the registered bundle identifier must match the applicationId in your project's build.gradle. For the full authentication story, see the Identity & Access Management Developer Guide.

Create a New Android Studio Project

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

1. From the Welcome to Android Studio dialogue box select Start a new Android Studio project to open the Create New Project dialog.
2. In the "Select a Project Template" dialog box select Empty Activity and click Next.
3. In the Configure Your Project dialog, under Name, specify an appropriate application name. The remainder of this tutorial uses BasicMapSolution as the application name.
4. Edit the package name in the Package name field. 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. Configure Your Project

5. Under Save Location specify an appropriate project location in the file system.
6. Under Minimum SDK select the lowest version of the Android SDK you wish to support. For this sample application use Android 4.4 "KitKat".
7. You may be prompted to agree to a License Agreement. Click Accept and then Next to install SDK components.
8. Click Finish.

Result: Android 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 structure, and the Project view shows a flattened view of the project 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

Import HERE SDK Android Archive

The SDK for Android library is shipped as an Android Archive (.AAR) file. You can import this library by doing the following:

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. 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 app/libs/ directory under your application.
4. 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 HERE SDK package.

Modify build.gradle

After importing the .AAR file modify build.gradle to add the file to your list of dependencies.

1. From the Project view pane locate the build.gradle file under the app folder and open it for editing.
2. In build.gradle add the following line into the dependencies { ... } section:

   implementation files('libs/HERE-sdk.aar')

3. Optional: If you plan on extending this application with HERE Places, Custom Locations, or Transit Routing functionality, add the GSON library to your project. You can add this library by adding the following line into the dependencies { ... } section:

   implementation 'com.google.code.gson:gson:2.8.0'

Modify AndroidManifest.xml and Add HERE Credentials

1. Add the HERE credentials to AndroidManifest.xml. For instructions on how to edit this file, see Add Credentials to the Manifest.
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.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.
   Note: Starting in API level 19 android.permission.WRITE_EXTERNAL_STORAGE is no longer required if the map disk cache(See MapSettings.setDiskCacheRootPath(path)) is set under an application-specific file directory.

Result: Your project is able to make use of APIs from 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.AndroidXMapFragment"
     android:id="@+id/mapfragment"
     android:layout_width="match_parent"
     android:layout_height="match_parent"/>

Result: When AndroidXMapFragment is initialized, your application's BasicMapActivity contains a AndroidXMapFragment UI element (with the mapfragment ID) 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 AndroidXMapFragment class, thus creating and associating a Map with the AndroidXMapFragment 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.AndroidXMapFragment;
  import androidx.fragment.app.FragmentActivity;
  
  public class BasicMapActivity extends FragmentActivity {
  
    // map embedded in the map fragment
    private Map map = null;
  
    // map fragment embedded in this activity
    private AndroidXMapFragment 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 = (AndroidXMapFragment) getSupportFragmentManager().findFragmentById(R.id.mapfragment);
  
      // Set up disk map cache path for this application
      // Use path under your application folder for storing the disk cache
      com.here.android.mpa.common.MapSettings.setDiskCacheRootPath(
        getApplicationContext().getExternalFilesDir(null) + File.separator + ".here-maps");
  
      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, it needs to ask users to grant certain permissions at runtime. For more information about this requirement, see Requesting Android Permissions.

Run the Application

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 data connection is enabled.

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