Quick Start Guide for Android MapKit3D SDK

Introduction

This document describes the features of the Android™ MapKit3D software development kit (SDK) application and demonstrates the usage of the various major application programming interfaces (APIs) on the map.

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 MapKit3D 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 MapKit3D SDK.

Getting the SDK

To obtain the Android MapKit3D SDK, perform the following steps:

  1. Go to https://git.location.studio/location.studio/androidSDK/tree/master.

  2. Register or sign in to your existing Comtech Location Studio® Git account.

  3. If you created a new account, access it by clicking the Confirm your account link sent to the registered email ID.

  4. 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

Follow the next sections to add a basic map to a sample Android application.

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

Project Setup

The following steps explain the project setup required to run the Android MapKit3D SDK.

  1. Start Android Studio.

  2. Start a new Android Studio project.

  3. Select an Empty Activity project and click Next as in the following screenshot.

Empact
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.

  1. 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 MapKit3D SDK. The SDK supports both Java and Kotlin™ programming languages. For this sample project, we are selecting Java in the Language dropdown.
Configure Project
Figure 2. Configuring the Project

Dependency Setup

This section describes the dependency set up for Android MapKit3D SDK APIs. The SDK contains the following two libraries:

  • ltk_common.aar

  • ltk_mapkit3d.aar

    1. 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.

New Module
Figure 3. Choosing New Module

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

Import .JAR/.AAR
Figure 4. Importing .JAR/.AAR Package

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

Selecting ltk_common.aar
Figure 5. Selecting ltk_common.aar

  1. Repeat the above activities in Step 1 and import the androidSDK/libproj/ltk_mapkit3d/ltk_mapkit3d.aar package.

Note
 ltk_mapkit3d.aar contains a prepackaged set of resources for different map elements like avatar, compass, pin and so on.

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

implementation project(path: ':ltk_common')
implementation project(path: ':ltk_mapkit3d')

Adding Permissions to AndroidManifest.xml

The following permissions must be declared inside the <manifest> tag in the AndroidManifest.xml file to make the Android MapKit3D 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 26 or higher, make sure to check ACCESS_FINE_LOCATION and READ_PHONE_STATE permissions during runtime using the PermissionsManager, before initializing the map 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 MapView to XML Layout

Add the MapKit3D MapView to the XML layout as shown in the following code snippet. Open the activity_main.xml and replace the <TextView …​/> with the folowiing code snippet.

<com.locationtoolkit.map3d.MapView
android:id="@+id/map_view"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:layout_constraintBottom_toBottomOf="parent"
app:layout_constraintLeft_toLeftOf="parent"
app:layout_constraintRight_toRightOf="parent"
app:layout_constraintTop_toTopOf="parent" />

Modifying the Code in the MapView

To initialize the MapView, add the code snippets shown in the following sections to the MainActivity’s onCreate() method. If you are targeting an API with a 26 or higher, you need to request for user permissions before using the MapKit3D 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");
ltkContextBuilder.setCountry("US");
ltkContextBuilder.setProductName("default");
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 MapOptions Object

The MapOptions object provides the basic configurations for the map to work. The following code snippet shows creation of the MapOptions object.

MapOptions mapOptions = new MapOptions();
mapOptions.cacheFolder = getFilesDir().getAbsolutePath() + "/mapkit3d";

Initializing the MapView

To get started, you need to add the following lines to import the necessary packages in the MainActivity.

import com.locationtoolkit.common.LTKContext;
import com.locationtoolkit.map3d.MapOptions;
import com.locationtoolkit.map3d.MapView;

The following code snippet shows how to get the reference of the MapView from the layout and then initialize it with the MapOptions and LTKContext objects.

MapView mapView = findViewById(R.id.map_view);
mapView.initialize(mapOptions, ltkContext);

Building and Running a Basic Map

The steps in Getting Started are sufficient to run and load the map in the sample app. You can see the map as shown in the following figure.

SampleMap
Figure 6. Basic Map

TroubleShooting

While building or running the sample app, if the following error occurs, disable 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.

InstantRun
Figure 7. Disabling the Instant Run