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

  • There are no restrictions on IDE version, but we recommend developers to use Arctic Fox | 2020.3.1 and above.

• Navigation SDK’s Android SDK levels

  • minSdkVersion 17

  • targetSdkVersion 29

  • compileSdkVersion 29

  • Play service location should be smaller than or equal to version 20.0.0(due to breaking changes: some Classes are now interfaces instead of classes, introduced on October 13, 2022, v21.0.0) com.google.android.gms:play-services-location:20.0.0

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

In your app-level build.gradle file, add the Nextbillion.ai dependency for the Navigation SDK for Android.

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

This code block adds the Nextbillion.ai Navigation SDK as a dependency to your Android app. This allows your app to use the functionality provided by the SDK. The SDK version used is "0.2.0" stored in a variable version. The ‘dependencies’ block is used to specify the libraries and frameworks your app depends on. The ‘implementation' keyword is used to declare a dependency on the Nextbillion Navigation SDK, the string 'ai.nextbillion:nb-navigation-android:$version' specifying the group, name, and version of the library(Navigation SDK). The "implementation" configuration indicates that this dependency is needed at runtime and it should be packaged with the APK.

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.

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

If your project doesn’t have an Application class, please make sure that you have called the code above before you instantiate a MapView or inflate any layout that contains a MapView, for example, call it before setContentView(R.layout.your_layout).

Add Permissions

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

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

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

For all code examples, refer to Navigation Code Examples

activity_main.xml view source

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:padding="10dp">

    <LinearLayout
        android:layout_width="wrap_content"
        android:layout_height="wrap_content">
        <Button
            android:id="@+id/fetchRoute"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:text="@string/fetch_route"/>

        <Button
            android:id="@+id/startNav"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_marginLeft="15dp"
            android:text="@string/start_navigation"/>
    </LinearLayout>

    <TextView
        android:id="@+id/routeGeometry"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginTop="10dp"/>

    <ProgressBar
        android:id="@+id/progress"
        android:visibility="gone"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center"/>

</LinearLayout>

NavigationActivity view source

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
package ai.nextbillion.navigation.demo.activity;

import android.os.Bundle;
import android.view.View;
import android.widget.Button;
import android.widget.ProgressBar;
import android.widget.TextView;

import ai.nextbillion.kits.directions.models.DirectionsResponse;
import ai.nextbillion.kits.directions.models.DirectionsRoute;
import ai.nextbillion.kits.geojson.Point;
import ai.nextbillion.maps.location.modes.RenderMode;
import ai.nextbillion.navigation.demo.R;
import ai.nextbillion.navigation.ui.NBNavigation;
import ai.nextbillion.navigation.ui.NavLauncherConfig;
import ai.nextbillion.navigation.ui.NavigationLauncher;
import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;
import retrofit2.Call;
import retrofit2.Callback;
import retrofit2.Response;

public class NavigationActivity extends AppCompatActivity implements View.OnClickListener {

    private Button fetchRoute;
    private Button startNav;
    private TextView routeGeometry;
    private DirectionsRoute directionsRoute;
    private ProgressBar progress;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        fetchRoute = findViewById(R.id.fetchRoute);
        startNav = findViewById(R.id.startNav);
        routeGeometry = findViewById(R.id.routeGeometry);
        progress = findViewById(R.id.progress);
        fetchRoute.setOnClickListener(this);
        startNav.setOnClickListener(this);
        startNav.setEnabled(false);

    }

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

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

                @Override
                public void onFailure(@NonNull Call<DirectionsResponse> call, @NonNull Throwable t) {
                    progress.setVisibility(View.GONE);
                }
            });
        } else if (view.getId() == R.id.startNav) {
            NavLauncherConfig.Builder configBuilder = NavLauncherConfig.builder(directionsRoute);
            configBuilder.locationLayerRenderMode(RenderMode.GPS);
            configBuilder.shouldSimulateRoute(true);
            NavigationLauncher.startNavigation(NavigationActivity.this, configBuilder.build());
        }
    }
}

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.