Getting Started

This page prepares the app to use Offline Maps by adding the SDK, confirming permissions/storage behavior, selecting the supported offline tile data source, and initializing RegionalOffline before building the download experience.

Install the SDK

Regional Offline Maps is an SDK service that manages offline map data across the application. It provides all the APIs to configure offline maps, download map packages, and enable the standard MapView which reads the installed data when network connectivity is unavailable. RegionalOffline is included in the nb-maps AAR and does not require a separate offline artifact.

Integrate the release version using the Maps SDK repository and credential configuration:

1
// settings.gradle.kts
2
dependencyResolutionManagement {
3
    repositories {
4
        google()
5
        mavenCentral()
6
    }
7
}
8
dependencies {
9
    implementation("ai.nextbillion:nb-maps-android:3.2.0")
10

11
    // The Kotlin Flow examples in this guide use the following Lifecycle extension. 
12

13
implementation("androidx.lifecycle:lifecycle-runtime-ktx:<lifecycle-version>")
14
}

Note: If your app also uses the Navigation SDK, make sure the Maps SDK version used by Offline Maps matches the Maps SDK version required by your Navigation SDK release.

Permissions and Storage

The SDK AAR already declares the base permissions for INTERNET and ACCESS_NETWORK_STATE:

1
<uses-permission android:name="android.permission.INTERNET" />
2
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

The application does not need to declare them again after manifest merging. By default, offline data is written to FileSource's app-specific resource directory and does not require shared-storage permission. Uninstalling the application, clearing application data, or explicitly deleting or moving this resource directory removes the offline data.

Tile Server Requirements

Initialize Nextbillion and select the tile server before initializing Offline Maps:

1
import ai.nextbillion.maps.Nextbillion
2
import ai.nextbillion.maps.style.NGLWellKnownTileServer
3

4
Nextbillion.getInstance(
5
    applicationContext,
6
    BuildConfig.NEXTBILLION_API_KEY
7
)

Regional Offline currently supports only NGLTomTom:

NGLWellKnownTileServer.NGLMapTiler can be used normally for online maps, but it cannot initialize, download, manage, or display Offline Maps. Check RegionalOffline.supportStatus() before showing the offline entry point. If it returns TOMTOM_REQUIRED, disable the entry point and prompt the user to switch to NGLTomTom.

Initialize Regional Offline Maps

RegionalOffline is the process-level entry point. The SDK maintains a single download-management instance internally, so the application does not need to create, retain, or release an additional client.

1
import ai.nextbillion.maps.Nextbillion
2
import ai.nextbillion.maps.regionaloffline.release.client.RegionalOffline
3
import ai.nextbillion.maps.regionaloffline.release.client.RegionalOfflineSupportStatus
4
import ai.nextbillion.maps.style.NGLWellKnownTileServer
5
import android.app.Application
6
import android.util.Log
7

8
class App : Application() {
9
    override fun onCreate() {
10
        super.onCreate()
11

12
        Nextbillion.getInstance(
13
            this,
14
            BuildConfig.NEXTBILLION_API_KEY,
15
            NGLWellKnownTileServer.NGLTomTom,
16
        )
17

18
        when (RegionalOffline.supportStatus()) {
19
            RegionalOfflineSupportStatus.SUPPORTED -> {
20
                if (!RegionalOffline.initialize(this)) {
21
                    Log.e("App", "Regional Offline initialization failed")
22
                }
23
            }
24
            RegionalOfflineSupportStatus.TOMTOM_REQUIRED ->
25
                Log.w("App", "Regional Offline requires NGLTomTom")
26
            RegionalOfflineSupportStatus.NEXTBILLION_NOT_INITIALIZED ->
27
                Log.e("App", "Initialize Nextbillion before Regional Offline")
28
        }
29
    }
30
}

To register Application in the manifest, use:

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

initialize() is thread-safe and idempotent. Repeated calls with the same CDN configuration return “true”. A different CDN configuration returns false and does not replace the running instance. It also returns false when the current tile server or the explicit RegionalOfflineConfig.dataSource is not TomTom. Calling RegionalOffline.initialize() is not required when the application only displays previously downloaded TomTom maps.

Custom CDN (Optional)

Most applications should use the default SDK endpoint. Configure a custom CDN only when you have deployed a complete region catalog, package set, and preview bundle matching the SDK version.

1
RegionalOffline.initialize(
2
    this,
3
    mapsBaseUrl = "https://your-cdn.example.com/path/maps",
4
)