Quick Start Guide for Android NavKit SDK

Introduction

This document describes the features of the Android™ Navigation API and demonstrates the usage of the various major application programming interfaces (APIs).

Prerequisites

The user must be familiar with the Android operating system, Android Studio development environment, and Java^® programming language
The Android Studio (version 3.4 or above) must be installed

Note	The Android NavKit software development kit (SDK) supports application programming interfaces (APIs) with a minimum version of 19 and above. This SDK is built targeting the Android APIs with version 28.

About API Key

The API key is used to track API requests of the project for usage and billing. API key often acts as a unique identifier and a secret token for authentication. The API key can be requested by filling in details and submitting the form at https://locationstudio.zendesk.com/hc/en-us/requests/new?ticket_form_id=360001758513.

Quick Start Steps

The following steps will help you to start using the Android NavKit SDK.

Getting the SDK

To obtain the Android SDK, perform the following steps:

Go to https://git.location.studio/location.studio/androidSDK/tree/master.
Register or sign in to your existing Comtech Location Studio^® Git account.
If you created a new account, access it by clicking the Confirm your account link sent to the registered email ID.
On the home page under the Project tab, click on the download icon drop-down menu to save the Android SDK zip package to your local drive. As an alternative, you can clone the repository to your local system using the following command.

git clone https://git.location.studio/location.studio/androidSDK.git

After you have downloaded and extracted the zip package or cloned the repository, follow the steps described in the next sections to begin using the SDK.

Getting Started

Getting Started

Follow the next sections to test a Navigation session in a sample Android application.

Note	The following steps are targeted for Android Studio with version 3.4. The steps may vary for other versions of the Android Studio.

Project Setup

The following steps explain the project setup required to create a sample app using the Android NavKit SDK.

Start Android Studio.
Start a new Android Studio project.
Select an Empty Activity project and click Next as shown below.

Figure 1. Selecting Empty Activity

Note	Other types of available projects can also be selected during the project setup, but this tutorial uses Empty Activity project for easy understanding.

In the Configure your project screen, enter your desired values for Name, Package name and all other fields as shown in the following screenshot.

Note	Make sure that the API version entered is at least 19. API versions of 19 and above are supported in the Android NavKit SDK. The SDK supports both Java and and Kotlin™ programming languages. For this sample project, we are selecting Java in the Language dropdown.

Figure 2. Configuring the Project

Dependency Setup

This section describes the dependency set up for Android NavKit SDK APIs. The NavKit SDK is part of the ltk_common.aar library. The following steps are performed to complete the dependency set up.

Import the ltk_common.aar, as described in the following steps.
- From the File menu select New, and then select New Module… as shown in the following screenshot.

Figure 3. Choosing New Module

Select Import .JAR/.AAR Package and click Next as shown in the following screenshot.

Figure 4. Import .JAR/.AAR Package

In the File name, browse to the androidSDK/libproj/ltk_common location, select the ltk_common.aar file and click Finish.

Figure 5. Selecting ltk_common.aar

Open the build.gradle of the app module and add the following dependencies:

implementation project(path: ':ltk_common')

Adding Permissions to AndroidManifest.xml

The following permissions must be declared inside the <manifest> tag in the AndroidManifest.xml file to make the Android NavKit SDK work.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Note	If the application targets an API with version 26 or higher, make sure to check ACCESS_FINE_LOCATION and READ_PHONE_STATE permissions during runtime using the PermissionsManager, before initializing the SDK related classes.

Note	For this sample application, you can set the target SDK version to less than or equal to 25 in the build.gradle of app module.

Adding Navigation Resources

The NavKit library makes use of resources that must be built as part of your package.

Note	The NavKit resources must be included in your assets. If not included, the SessionListener will not get fired and navigation will not work.

Copy the directory androidSDK/assets/NavKit/ to the assets folder of the app module and make sure that the NavKit resource folder appears under the assets folder as seen in the following figure.

Figure 6. Copying androidSDK/assets/NavKit/ to the Assets Folder

Creating a Navigation Session

The following sections describe the process to create a Navigation session. To get started, add the code snippets to the MainActivity’s onCreate() method. If you are targeting an API with version 26 or higher, you need to request for user permissions before using the NavKit classes.

Creating the LTKContext Object

For using the Location ToolKit (LTK) services, you must create a LTKContext object, a singleton instance of services through which you can configure the API Key, language, country, and so on as shown in the following code snippet.

LTKContext.Builder ltkContextBuilder = new LTKContext.Builder(
        getApplicationContext(), "PUT_YOUR_API_KEY_HERE", "en");
LTKContext ltkContext = ltkContextBuilder.buildLTKContext();

In the above code, you need to put the received API key in the place of “PUT_YOUR_API_KEY_HERE”.

Creating the RouteOptions Object

The class RouteOptions specifies the various settings which control the generated route. It provides the route configurations like route type, transportation mode, avoid, and so on.The available options are:

Route type - Easiest/Fastest/Shortest
Transportation - Bicycle/Car/Pedestrian/Truck
Avoid - Highway/Toll/Hov/Ferry

Note	Avoid contains either one or a combination of any of the available options.

The following code snippet shows the route configurations set using the RouteOptions class.

RouteOptions routeOptions = new RouteOptions(RouteOptions.ROUTE_FASTEST,
        RouteOptions.TRANSPORTATION_MODE_CAR,
        RouteOptions.AVOID_HIGHWAY | RouteOptions.AVOID_TOLL);

Creating the Navigation Preferences

The navigation Preferences class provides various navigation configurations like guidance, announcements in phonetic format, traffic alerts, measurement units and so on.

The following code snippet shows the configurations set using the Preferences class.

Preferences preferences = new Preferences();
// Enable Natural guidance
preferences.setNaturalGuidanceEnabled(true);
// Enable Lane guidance
preferences.setLaneGuidanceEnabled(true);
// Set supported phonetics formats
preferences.setSupportedPhoneticsFormats("IPA,NT-SAMPA,X-SAMPA");
// Set traffic navigation alert
preferences.setNavTrafficFor(Preferences.NAV_TRAFFIC_FOR_ALERT_ONLY);
// Set measurement unit
preferences.setMeasurement(LTKContext.Measurement.METRIC);

Starting a Navigation Session

Navigation class is the entry point of Navigation session. Creating a Navigation instance creates a Navigation session. To create a Navigation session, you need to provide LTKContext, destination place, route options, and navigation preferences as shown in the following code snippet.

// Create a sample destination location
Location destLocation = new Location(); // New York City
destLocation.setLatitude(40.661);
destLocation.setLongitude(-73.944);


// Get navigation session
final Navigation navigation = Navigation.getNavigation(
        ltkContext,
        new Place(destLocation),
        routeOptions,
        preferences);

Registering Navigation Listeners

There are various navigation listeners available to track Navigaton events. The session listener is added to receive Navigation session related events, as shown in the following code snippet. SessionListener has various methods to notify route received, route error, route progress, off route and so on.

navigation.addSessionListener(new SessionListener() {
    @Override
    public void offroute() {
        Log.d("SessionListener", "offroute()");
    }

    @Override
    public void onroute() {
        Log.d("SessionListener", "onroute()");
    }

    @Override
    public void routeReceived(int i, RouteInformation[] routeInfo) {
        Log.d("SessionListener", "routeReceived()");
    }

    @Override
    public void routeRequested(int i) {
        Log.d("SessionListener", "routeRequested()");
    }

    @Override
    public void routeProgress(int i) {
        Log.d("SessionListener", "routeProgress()");
    }

    @Override
    public void routeError(LTKException e) {
        Log.d("SessionListener", "routeError()");
    }

    @Override
    public void routeFinish() {
        Log.d("SessionListener", "routeFinish()");
    }

    @Override
    public void routeUpdating() {
        Log.d("SessionListener", "routeUpdating()");
    }
});

Updating a Navigation Session

To update a Navigation session, you need to send each GPS location update to the created Navigation instance as shown in the following code snippet.

navigation.updatePosition(position);

The first position update triggers a route generation. The location updates can be simulated as shown in the following code snippet for this example.

final Location position = new Location(); // Washington, D.C.
position.setLatitude(38.904722);
position.setLongitude(-77.016389);
position.setAltitude(300);
position.setAccuracy(10);
position.setHorizontalVelocity(10);
position.setHeading(10);
final Handler handler = new Handler();
final Runnable runnable = new Runnable() {
    @Override
    public void run() {
        try {
            position.setGpsTime(System.currentTimeMillis());
            navigation.updatePosition(position);
        } finally {
            handler.postDelayed(this, 1000);
        }
    }
};
runnable.run();

Building and Running the Sample App

Using the preceding code snippets, you can test the initialization and creation of the navigation session in the sample app. On building and running the sample app, you can see the navigation session creation logs in the LogCat as shown in the following screenshot.

Figure 7. Navigation Session Logs

TroubleShooting

While building or running the sample app, if you get the following error, disable the Instant Run located under Settings of the Android Studio.

Caused by: java.lang.IllegalStateException: Unexpected constructor structure.

Go to File → Settings… → Build, Execution, Deployment → Instant Run, as shown in the following screenshot. By default, the highlighted option in the screenshot is enabled. To resolve the error, you need to uncheck the box and disable it.

Figure 8. Disabling the Instant Run