Getting Started

This section lists how to configure offline navigation, initialize the SDK during app startup, and understand initialization state, concurrency behavior, and health checks.

Install the SDK with Swift Package Manager

Package URL: GitHub - nextbillion-ai/navigation-distribution

The NextBillion Navigation package product includes NbmapNavigation, NbmapCoreNavigation, Nbmap, and Turf. Do not add a separate, older Maps SDK package when using Swift Package Manager.

Configure runtime behavior

Configure the Offline Navigation runtime once, then initialize the offline subsystem during app startup. Repeated or concurrent initialization calls with the same configuration are safe.

Configure the route mode and offline download network policy before calling initializeOffline.

1
import NbmapCoreNavigation
2

3
let runtimeConfig = NBNavigation.NavigationRuntimeConfig(
4
    routing: RoutingConfig(mode: .smart),
5
    offlineDownloadNetworkPolicy: .wifiOnly
6
)
7
NBNavigation.setNavigationRuntimeConfig(runtimeConfig)

The default download policy is wifiOnly.
Use anyNetwork to allow cellular downloads.
NBNavigation can be used to update the routing strategy and download network policy.

Configuration requirement

NBNavigation configures the offline map base URL centrally. Do not read or set resolvedBaseURL, and do not repeatedly configure the Maps offline runtime in application methods.

Initialize during app startup

1
func application(
2
    _ application: UIApplication,
3
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
4
) -> Bool {
5
    NGLAccountManager.accessToken = "YOUR_ACCESS_KEY"
6
    Task {
7
        do {
8
            try await NBNavigation.initializeOffline()
9
        } catch {
10
            print("Offline initialization failed: \(error.localizedDescription)")
11
        }
12
    }
13
    return true
14
}

initializeOffline configures the offline map runtime and initializes the offline routing engine. Concurrent calls with the same valid configuration wait for the same task. Calls made after successful initialization return immediately.

Initialization behavior

Scenario	SDK behavior	Integration guidance
Concurrent calls with the same configuration	Waits for the same initialization task	Safe to call directly
Repeated calls with the same configuration	Returns immediately after successful initialization	No once flag required
Different configuration while initialization is in progress	Throws `invalidConfig`	Use one configuration source
Initialization fails	Enters the failed state and retains the error	Call initializeOffline again after correcting the cause
Initialization has not started	Offline APIs throw `engineNotInitialized`	Start initialization first

Initialization state and loading screens

It is recommended to use state only to drive the UI

1
switch NBNavigation.getOfflineInitializationState() {
2
case .notStarted:    showStartRequired()
3
case .initializing:  showLoading()
4
case .initialized:   showContent()
5
case .failed:        showRetry()
6
case .shuttingDown:  showClosing()
7
}
8

9
// Use only when the screen has a separate loading phase.
10
try await NBNavigation.waitUntilOfflineInitialized()

waitUntilOfflineInitialized does not start initialization. It throws engineNotInitialized when the state is notStarted and rethrows the original error after a failed initialization. Call initializeOffline to start or retry initialization.

Initialization state

Use isOfflineInitialized only to update UI state, such as displaying a loading indicator. Do not use it to decide whether an offline routing API can be called. Call the API directly and await its result. Offline routing APIs automatically wait for initialization that is already in progress and throw an error if initialization has not started or has failed. If a screen requires a separate initialization loading phase, call waitUntilOfflineInitialized().

Post Initialization Health Check

In order to test and run diagnostics after Initialization, use:

1
do {
2
    let health = try await NBNavigation.checkOfflineHealth()
3
    print("offline state=\(health.state)")
4
    print("data root=\(health.dataRoot)")
5
    print("routing tiles=\(health.loadedTileCount)")
6
} catch {
7
    print("Offline initialization failed: \(error.localizedDescription)")
8
}

Please note that:

checkOfflineHealth reports the engine state after initialization. A successful call confirms that the native gateway can respond to queries.
A loadedTileCount of 0 means that no routing tiles are loaded; it does not indicate an initialization failure.
health.state is a diagnostic field and should not be treated as a stable application enum.

Recommended call sequence

Configure the route mode and download network policy.
Call initializeOffline during app startup.
On the offline screen, synchronize the catalog, and then read the combined region list.
Subscribe to progress updates before calling downloadRegion.
Send all route requests through NBNavigation.fetchRoute. RouteMode determines the online and offline strategy.

Key takeaways

Call NBNavigation.initializeOffline as early as possible after app launch. Repeated or concurrent calls with the same configuration reuse the same initialization task.
Offline routing APIs such as listOfflineRegions, syncOfflineRegionList, and downloadRegion wait for an initialization already in-progress, but they do not start initialization.
Routing data and map tiles are separate datasets linked by regionId. downloadRegion starts both downloads, but the combined operation is not a database transaction.
An in-place update of the same app normally preserves offline data. Uninstalling and reinstalling the app deletes its sandbox. Use the SDK's default dataRoot whenever possible.