SDK setup (v2.1.x - Android)

Requirements

The SDK supports Android 4.1 (API Level 16, "Jelly Bean") or higher and the following ABIs:

• armeabi-v7a
• arm64-v8a
• x86
• x86_64

Integrating the SDK

Adding the dependencies

Using a version from the Maven repository

Insert the following code into your app's build.gradle:

repositories {
	google()
	mavenCentral()
	maven {
    	url 'https://maven.navmii.com/artifactory/navmii-public'
	    credentials {
	    	username "public"
	        password "public1&"
	    }
    }
}

dependencies {
    implementation('com.navmii.android:sdk:2.3.0-398')
}

Using an AAR library from a ZIP archive

Insert the following code into your app's build.gradle:

repositories {
	google()
	mavenCentral()
    flatDir {
        dirs '<path_to_navmiisdk_aar>'
    }
}

dependencies {
    implementation(name: 'navmiisdk-<sdk_version>', ext: 'aar')
}

Adding API Key to the Manifest

Add the following lines to the AndroidManifest.xml of your application within the <application></application> block:

<meta-data android:name="com.navmii.sdk.API_KEY" android:value="YOUR_API_KEY" />

Setting the permissions

Add the following lines to the AndroidManifest.xml within the <manifest></manifest> block:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

The apps targeting Android 5.0 (API level 21) or higher must also include the following line:

<uses-feature android:name="android.hardware.location.gps" />

Limitations

This version of Navmii SDK doesn't support working with multiple instances of MapView at the same time. The SDK supports only one visible MapView instance at a time. Displaying multiple instances of MapView will result in an undefined behaviour.

Working with the SDK

The key component of the SDK is a singleton instance of  the Sdk class, which can be received with Sdk.getInstance() static method. To initialize the Sdk and start map rendering use the static Sdk.initSdkAsync method. This method takes ConfigurationSettings as an argument. To deinitialize the SDK use the Sdk.deinitializeSdk method. The Sdk.pause and Sdk.resume methods only start and stop map rendering respectively, without initializing/deinitializing the SDK.

To see code examples of initializing the SDK please refer to Creating the Map View section. ConfigurationSettings are described in the SDK Configuration Settings section below.

Here's the most typical example of the last three methods usage:

    @Override
    protected void onPause() {
        super.onPause();

        Sdk.getInstance().pause();
    }

    @Override
    protected void onResume() {
        super.onResume();

        Sdk.getInstance().resume();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();

		if (Sdk.getInstance().getState() == Sdk.State.INITIALIZING ||
                Sdk.getInstance().getState() == Sdk.State.INITIALIZED) {

            Sdk.getInstance().deinitializeSdk();
        }
    }

SDK Configuration Settings

The ConfigurationSettings class represents the settings with which the SDK can be launched. If you have the resources designated to customize the map, you can specify the path to these resources via the setCustomResourcesPath method.

The SDK can use either online or offline map data, this can be selected via the setMapMode method. Call it with Sdk.ConfigurationSettings.MapMode.ONLINE or Sdk.ConfigurationSettings.MapMode.OFFLINE to use online or offline maps, respectively. When offline mode is selected, the path to the folder with maps has to be specified via the setOfflineMapsPath method.

You can also specify the path to the folder where the SDK puts files created at runtime.

To create a ConfigurationSettings instance use the ConfigurationSettings.Builder:

	        Sdk.ConfigurationSettings configurationSettings =
                new Sdk.ConfigurationSettings.Builder()
                        .setOfflineMapsPath(thePath)
                        .build();

Beta maps

When the SDK is configured to use online map data, it uses stable release maps by default. If you need more up-to-date map data, you can use Sdk.ConfigurationSettings.Builder.setUseOnlineBetaMaps(true) method to switch to beta maps. Please note that beta maps may contain errors which are not present in the release ones, therefore it's not recommended to use them in production.

If the SDK is configured to use offline map data, this method has no effect.

SDK State

The SDK can have four possible states represented by the Sdk.State enum:

• UNINITIALIZED
• INITIALIZING
• INITIALIZED
• INITIALIZATION_FAILED

The SDK can be used only when it's in INITIALIZED state. You can retrieve the current state through the Sdk.getState method.

The process of the SDK's initialization is asynchronous. To be informed on the initialization finish implement the StateChangeListener interface:

private class SdkStateListener implements Sdk.StateChangeListener {

    // Can only happen between onStart - onStop.
    @Override
    public void onStateChanged(Sdk.State state) {
        switch (state) {
            case UNINITIALIZED:
                break;
            case INITIALIZING:
                break;
            case INITIALIZED:
                break;
            case INITIALIZATION_FAILED:
                break;
        }
    }
}

private final Sdk.StateChangeListener stateChangeListener = new SdkStateListener();

@Override
public void onStart() {
    super.onStart();

    // Check - what if SDK initialization has failed between onStop - onStart.
    if (Sdk.getInstance().getState() == Sdk.State.INITIALIZATION_FAILED) {
        // Show an error message
    }

    Sdk.getInstance().addStateChangeListener(stateChangeListener);