Getting Started

Use this guide to set up the Android application for Offline Navigation by adding the SDK, configuring Android permissions, applying runtime behavior, and initializing Maps and NBNavigation in the correct order.

Install the SDK

Add Navigation Android SDK 3.0.1 to the application module. The AAR transitively supplies the verified Maps SDK version used by offline navigation. Do not force a different Maps SDK version unless NextBillion.ai Support explicitly instructs you to do so.

Kotlin DSL

1
// settings.gradle.kts
2
import org.gradle.api.initialization.resolve.RepositoriesMode
3

4
dependencyResolutionManagement {
5
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
6
    repositories {
7
        google()
8
        mavenCentral()
9
    }
10
}
11

12
// app/build.gradle.kts
13
dependencies {
14
    implementation("ai.nextbillion:nb-navigation-android:3.0.1")
15

16
// Sample application dependency only
17
    implementation("androidx.activity:activity-ktx:1.9.3")
18
}

Groovy DSL

1
// settings.gradle
2
dependencyResolutionManagement {
3
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
4
    repositories {
5
        google()
6
        mavenCentral()
7
    }
8
}
9

10
// app/build.gradle
11
dependencies {
12
    implementation "ai.nextbillion:nb-navigation-android:3.0.1"
13
    implementation "androidx.activity:activity-ktx:1.9.3"
14
}

If NextBillion.ai provides your organization with a private Maven repository, add that repository alongside mavenCentral() using the URL and read-only credentials supplied for your deployment. Store those credentials in the user-level Gradle properties file or CI secrets. Application consumers do not need the centralUsername or centralToken publishing credentials used by the SDK release pipeline.

Configure permissions

Declare only the permissions required by the features that the application uses. Catalog synchronization and regional downloads require network access but do not require location permission. Continuous turn-by-turn navigation normally uses location and a location-type foreground service.

Manifest Declarations

1
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
2
    <!-- Required for catalog sync, data download, and online routing. -->
3
    <uses-permission android:name="android.permission.INTERNET" />
4
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
5

6
    <!-- Required only when the app uses device location or starts navigation. -->
7
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
8
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
9

10
    <!-- Required for continuous navigation in a foreground service. -->
11
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
12
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
13

14
    <!-- Runtime permission on Android 13 / API 33 and later. -->
15
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
16
</manifest>

Permission Requirements

Runtime Rules

• Request location permission only when the user selects a feature that needs location. Downloading offline data by regionId does not require location permission.

• On Android 12 and later, request COARSE and FINE together when the navigation experience needs precise location. Continue with reduced functionality or stop the flow if the user grants only an approximate location.

• On Android 13 and later, POST_NOTIFICATIONS is not required to start a foreground service, but a denied permission prevents normal display of the navigation notification in the notification drawer.

• Starting with Android 14 (API level 34), applications running a location-based foreground service must declare the FOREGROUND_SERVICE_LOCATION permission in their manifest. Users must also turn on system location services and grant either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION before navigation starts. Note that precise turn-by-turn guidance typically requires ACCESS_FINE_LOCATION. Since location access is treated as a "while-in-use" permission, initiate the navigation foreground service while an “Activity” is actively visible on screen. ACCESS_BACKGROUND_LOCATION is not necessary for standard visible starts, and is only needed if your application explicitly launches or retrieves location updates from the background where platform policies permit.

• The Navigation AAR declares its navigation service and location foreground-service type. Do not redeclare the SDK service unless a documented manifest override is required.

Configure runtime behavior

Configure the route mode and download network policy before users start offline routing or region downloads. Offline-capable apps should usually switch from the default online-only behavior to a mode such as SMART, then keep the selected download policy consistent when updating runtime configuration.

1
NBNavigation.setRuntimeConfig(
2
    RouteMode.SMART,
3
    NBNavigation.getDownloadNetworkPolicy()
4
)

Runtime configuration applies to the current application process. Reapply the intended route mode and download policy during application startup before opening offline navigation screens.

Initialize Maps during app startup

Initialize the Maps SDK first in your custom application. If Maps is already initialized, do not initialize it again with a different access key, tile server, or CDN. Please note that offline maps require NGLTomTom.

1
class MyApplication : Application() {
2
    override fun onCreate() {
3
        super.onCreate()
4
        val accessKey = getString(R.string.nextbillion_access_key)
5
        Nextbillion.getInstance(
6
            this,
7
            accessKey,
8
            NGLWellKnownTileServer.NGLTomTom
9
        )
10
    }
11
}

1
<application
2
    android:name=".MyApplication"
3
    ... />

Initialize Offline Navigation

Follow the below steps to initialize offline navigation successfully:

1. Call NBNavigation.initialize() after Nextbillion.(@NonNull Context context, @Nullable String apiKey) is called.

2. Initialization is process-wide, consequently, concurrent calls are coalesced into the same operation.

3. After initialization succeeds, a subsequent initialize() call returns immediately without shutting down or restarting the engine.

Application code should still manage state centrally through an application-scoped Repository or Manager.

1
fun initializeOfflineNavigation() {
2
    NBNavigation.initialize(object : NBNavigationTaskCallback<Void> {
3
        override fun onSuccess(result: Void?) {
4
            loadRegionCatalog(force = false)
5
        }
6
 
7
        override fun onError(throwable: Throwable) {
8
            showOfflineError("Offline initialization failed", throwable)
9
        }
10
    })
11
}

syncRegions() also protects the default engine with automatic initialization and waits for any initialization already in progress. Production applications should still call initialize() explicitly so they can handle errors and readiness before opening the offline screen.

Callback threading and state handling

Native and network completion callbacks are posted to the main thread. Parameter validation failures and some immediate results may be returned synchronously. Do not assume that a callback will always occur after the current call stack returns.

Engine shutdown

Do not call NBNavigation.shutdown() when a normal Activity or Fragment is destroyed or when one navigation session ends.

Shut it down only when the process explicitly disables the entire offline capability. Note that a shutdown does not delete data. Call initialize() again before subsequent use.

Recommended call sequence

Use the following recommended call sequence:

1. Initialize the Maps SDK with the TomTom tile server in application.

2. Call NBNavigation.initialize() to initialize offline navigation.

3. Read the local catalogs first for immediate display, then synchronize with AUTO and refresh the list.

4. Download the region by regionId, and observe routeNetwork and mapTile progress.

5. Set RouteMode, then continue using NBNavigation.fetchRoute() and the existing navigation screens.