Get Started

This section is designed to help developers quickly and easily get up and running with the Navigation SDK. It covers the prerequisites and requirements for using the SDK, as well as detailed installation instructions and information on Maven dependencies. By following the steps outlined in this section, developers can quickly set up the Navigation SDK and start building engaging navigation experiences for their users. Additionally, it includes a Quickstart guide to creating a simple navigation app using the SDK, allowing developers to quickly see the Navigation SDK in action and get a feel for its capabilities.

Prerequisites and requirements for using the SDK

Our Android Navigation SDK require the following prerequisites:

  • Access Key: if you don’t have your Access Key yet, don’t hesitate to contact us

  • IDE (Android Studio): to build and develop the Android application

    • Use the latest stable Android Studio version recommended by Google

  • Navigation SDK’s Android SDK levels

    • minSdkVersion 23

    • targetSdkVersion 34

    • compileSdkVersion 34

    • Use the Google Play services location version compatible with your project and this SDK release. Refer to the latest release notes for the recommended version.

Installation instructions

The section explains how to install the SDK by adding the necessary dependencies to your project. It provides instructions on adding the maven dependencies of SDK to your app's build.gradle file.

Maven Dependencies

Add the NextBillion Android Navigation SDK dependency in your app-level build.gradle file.

1
dependencies {
2
    def version = "2.7.1"
3
    implementation "ai.nextbillion:nb-navigation-android:$version"
4
}

It is recommended to use a single version policy: set def version = "2.7.1" and keep all explanatory text aligned with that version.

Initialization

The Navigation SDK is dependent on the Maps SDK, before we start using any functionalities from both SDKs, we need to initialize the Maps SDK first.

Initializing means passing your Access Key to the singleton method of the class Nextbillion, A common way to initialize the SDK is to put the following code in an application’s onCreate() callback.
Otherwise, please make sure you have called the code below before using any SDK functionalities.

1
Nextbillion.getInstance(getApplicationContext(), "your access key");

If your project does not have an Application class, call initialization before invoking any SDK APIs (route fetching, NavigationLauncher, embedded NavigationView, or map rendering).

Add Permissions

To use all functions of Navigation SDK, you need to declare the required permissions in the AndroidManifest.xml file

1
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
2
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION"/> 
3
<uses-permission android:name="android.permission.INTERNET" />
4
// Runtime permissions
5
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
6
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
7
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
8

Requesting Runtime Permissions in Your App:

Request runtime permissions in your app before starting navigation. At minimum, request foreground location; request background location and notifications only when those features are used.

1
// Check if the ACCESS_FINE_LOCATION permission is granted
2
if (ContextCompat.checkSelfPermission(this.getApplicationContext(),
3
        Manifest.permission.ACCESS_FINE_LOCATION)
4
        == PackageManager.PERMISSION_GRANTED) {
5
    mLocationPermissionGranted = true;
6
} else {
7
    // Request the location permission
8
    ActivityCompat.requestPermissions(this,
9
            new String[]{Manifest.permission.ACCESS_FINE_LOCATION},
10
            PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION);
11
}
12


13
// If permission isn't granted, show an error message
14
if (!mLocationPermissionGranted) {
15
    displayMessage("Error loading Navigation SDK: "
16
            + "The user has not granted location permission.");
17
    return;
18
}

Handling Permissions on Android 14 (API 34) and Above:

For Android 14+ foreground navigation, declare FOREGROUND_SERVICE_LOCATION in AndroidManifest and configure the foreground service type correctly. Request runtime permissions according to your app flow for location/notifications.

1
// Check for FOREGROUND_SERVICE_LOCATION permission (API 34+)
2
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) { // Android 14+
3
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.FOREGROUND_SERVICE_LOCATION)
4
            != PackageManager.PERMISSION_GRANTED) {
5
        ActivityCompat.requestPermissions(this,
6
                new String[]{Manifest.permission.FOREGROUND_SERVICE_LOCATION},
7
                REQUEST_FOREGROUND_SERVICE_LOCATION);
8
    }
9
}
10

Handling Background Location Permission (Android 10+):

If your app needs to provide navigation prompts in the background, you need to request the ACCESS_BACKGROUND_LOCATION permission for Android 10 and above.

1


2
// Check for ACCESS_BACKGROUND_LOCATION permission (Android 10+)
3
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) { // Android 10+
4
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_BACKGROUND_LOCATION)
5
            != PackageManager.PERMISSION_GRANTED) {
6
        ActivityCompat.requestPermissions(this,
7
                new String[]{Manifest.permission.ACCESS_BACKGROUND_LOCATION},
8
                REQUEST_BACKGROUND_LOCATION_PERMISSION);
9
    }
10
}

Handling Notification Permission (Android 13+):

If you want your app to send turn-by-turn notifications while running in the background, you need to request the POST_NOTIFICATIONS permission on Android 13 (API 33) and above.

1
// Check for POST_NOTIFICATIONS permission (Android 13+)
2
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { // Android 13+
3
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS)
4
            != PackageManager.PERMISSION_GRANTED) {
5
        ActivityCompat.requestPermissions(this,
6
                new String[]{Manifest.permission.POST_NOTIFICATIONS},
7
                REQUEST_NOTIFICATION_PERMISSION);
8
    }
9
}

Handling Permission Request Results:

Use Activity Result API as the primary permission-result handling approach. Keep onRequestPermissionsResult only for backward compatibility if required.

1
@Override
2
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
3
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
4


5
    if (grantResults.length == 0) {
6
        // Handle the case where the user closed the permission dialog without making a choice
7
        Toast.makeText(this, "Permission request was canceled", Toast.LENGTH_SHORT).show();
8
        return;
9
    }
10


11
    switch (requestCode) {
12
        case REQUEST_LOCATION_PERMISSION:
13
            handlePermissionResult(grantResults[0], "Location permission is required for this demo");
14
            break;
15


16
        case REQUEST_BACKGROUND_LOCATION_PERMISSION:
17
            handlePermissionResult(grantResults[0], "Background location permission is required if you run navigation in the background");
18
            break;
19


20
        case REQUEST_FOREGROUND_SERVICE_LOCATION:
21
            handlePermissionResult(grantResults[0], "Foreground location service permission is required if you run navigation in the foreground");
22
            break;
23


24
        case REQUEST_NOTIFICATION_PERMISSION:
25
            handlePermissionResult(grantResults[0], "Notification permission is required if you run navigation in the background");
26
            break;
27
    }
28
}
29


30
/**
31
 * Helper method to handle permission results.
32
 */
33
private void handlePermissionResult(int grantResult, String denialMessage) {
34
    if (grantResult != PackageManager.PERMISSION_GRANTED) {
35
        // Show a message if permission is denied
36
        Toast.makeText(this, denialMessage, Toast.LENGTH_LONG).show();
37
    }
38
}

Quickstart Guide

A complete turn-by-turn experience using the default NavigationLauncher

This example shows how to launch Navigation using NavigationLauncher

  • How to fetch a route using NBNavigation.fetchRoute with origin and destination

  • How to config NavLauncherConfig and launch Navigation using NavigationLauncher with the given route

documentation image

For all code examples, refer to Navigation Code Examples

activity_main.xml view source

1
<?xml version="1.0" encoding="utf-8"?>
2
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
3
    android:layout_width="match_parent"
4
    android:layout_height="match_parent"
5
    android:orientation="vertical"
6
    android:padding="10dp">
7


8
    <LinearLayout
9
        android:layout_width="wrap_content"
10
        android:layout_height="wrap_content">
11
        <Button
12
            android:id="@+id/fetchRoute"
13
            android:layout_width="wrap_content"
14
            android:layout_height="wrap_content"
15
            android:text="@string/fetch_route"/>
16


17
        <Button
18
            android:id="@+id/startNav"
19
            android:layout_width="wrap_content"
20
            android:layout_height="wrap_content"
21
            android:layout_marginLeft="15dp"
22
            android:text="@string/start_navigation"/>
23
    </LinearLayout>
24


25
    <TextView
26
        android:id="@+id/routeGeometry"
27
        android:layout_width="wrap_content"
28
        android:layout_height="wrap_content"
29
        android:layout_marginTop="10dp"/>
30


31
    <ProgressBar
32
        android:id="@+id/progress"
33
        android:visibility="gone"
34
        android:layout_width="wrap_content"
35
        android:layout_height="wrap_content"
36
        android:layout_gravity="center"/>
37


38
</LinearLayout>

NavigationActivity view source

1
package ai.nextbillion.navigation.demo.activity;
2


3
import android.os.Bundle;
4
import android.view.View;
5
import android.widget.Button;
6
import android.widget.ProgressBar;
7
import android.widget.TextView;
8


9
import ai.nextbillion.kits.directions.models.DirectionsResponse;
10
import ai.nextbillion.kits.directions.models.DirectionsRoute;
11
import ai.nextbillion.kits.geojson.Point;
12
import ai.nextbillion.maps.location.modes.RenderMode;
13
import ai.nextbillion.navigation.demo.R;
14
import ai.nextbillion.navigation.ui.NBNavigation;
15
import ai.nextbillion.navigation.ui.NavLauncherConfig;
16
import ai.nextbillion.navigation.ui.NavigationLauncher;
17
import androidx.annotation.NonNull;
18
import androidx.appcompat.app.AppCompatActivity;
19
import retrofit2.Call;
20
import retrofit2.Callback;
21
import retrofit2.Response;
22


23
public class NavigationActivity extends AppCompatActivity implements View.OnClickListener {
24


25
    private Button fetchRoute;
26
    private Button startNav;
27
    private TextView routeGeometry;
28
    private DirectionsRoute directionsRoute;
29
    private ProgressBar progress;
30
    @Override
31
    protected void onCreate(Bundle savedInstanceState) {
32
        super.onCreate(savedInstanceState);
33
        setContentView(R.layout.activity_main);
34
        fetchRoute = findViewById(R.id.fetchRoute);
35
        startNav = findViewById(R.id.startNav);
36
        routeGeometry = findViewById(R.id.routeGeometry);
37
        progress = findViewById(R.id.progress);
38
        fetchRoute.setOnClickListener(this);
39
        startNav.setOnClickListener(this);
40
        startNav.setEnabled(false);
41


42
    }
43


44
    @Override
45
    public void onClick(View view) {
46
        if (view.getId() == R.id.fetchRoute) {
47
            progress.setVisibility(View.VISIBLE);
48
            Point origin = Point.fromLngLat(103.75986708439264, 1.312533169133601);
49
            Point destination = Point.fromLngLat(103.77982271935586, 1.310473772283314);
50


51
            NBNavigation.fetchRoute(origin, destination, new Callback<DirectionsResponse>() {
52
                @Override
53
                public void onResponse(@NonNull Call<DirectionsResponse> call, @NonNull Response<DirectionsResponse> response) {
54
                    progress.setVisibility(View.GONE);
55
                    //start navigation with the route we just fetched.
56
                    if (response.body() != null && !response.body().routes().isEmpty()) {
57
                        directionsRoute = response.body().routes().get(0);
58
                        routeGeometry.setText(String.format("Route Geometry: %s", directionsRoute.geometry()));
59
                        startNav.setEnabled(true);
60
                    }
61
                }
62


63
                @Override
64
                public void onFailure(@NonNull Call<DirectionsResponse> call, @NonNull Throwable t) {
65
                    progress.setVisibility(View.GONE);
66
                }
67
            });
68
        } else if (view.getId() == R.id.startNav) {
69
            NavLauncherConfig.Builder configBuilder = NavLauncherConfig.builder(directionsRoute);
70
            configBuilder.locationLayerRenderMode(RenderMode.GPS);
71
            configBuilder.shouldSimulateRoute(true);
72
            NavigationLauncher.startNavigation(NavigationActivity.this, configBuilder.build());
73
        }
74
    }
75
}

Code Highlights

The example code represents a NavigationActivity class that allows users to fetch a route and start navigation using the NavigationLauncher class provided by the navigation SDK.

Code Explanation

The code example defines a layout file activity_main.xml that contains a vertical LinearLayout with two Button views (fetchRoute and startNav), a TextView (routeGeometry), and a ProgressBar(progress).

The associated Java class NavigationActivity extends AppCompatActivity and implements the OnClickListener interface. In the onCreate method, the layout elements are initialized and click listeners are set for the buttons.

When the fetchRoute button is clicked, a network request is made using the NBNavigation class to fetch a route between two geographic points (origin and destination). The response is received asynchronously in the onResponse callback. If the response is successful and contains at least one route, the first route is stored in the directionsRoute variable, and its geometry is displayed in the routeGeometry text view. The startNav button is enabled to allow navigation to be started.

When the startNav button is clicked, a NavLauncherConfig is created with the stored directionsRoute and some configuration options. The navigation is then started using the NavigationLauncher.startNavigation method.

Code summary

Fetch a route

  • Using the NBNavigation.fetchRoute method to retrieve the directions response for the given origin and destination points. If the response is successful and it will contain at least one route

Start navigation

  • NavLauncherConfig object is created with the previously fetched route and additional configuration options such as location layer render mode and route simulation. The NavigationLauncher.startNavigation method is called to start the navigation activity with the provided configuration.