Offline Navigation Integration: Complete Implementation Guide Blog

Reliable navigation starts with preparing for the conditions drivers face on the road, including unreliable connectivity. Whether a fleet serves rural communities, travels along remote highways or makes deliveries in areas with interrupted coverage, a driver app needs to remain useful when the network becomes unavailable.

Offline navigation helps developers address this challenge by bringing essential mapping and routing capabilities onto the device. 

With NextBillion.ai’s Offline Navigation SDK, applications can use downloaded regional maps and routing data to display maps, calculate routes and guide drivers within those regions without an internet connection.

This guide takes you step by step through integrating offline navigation using NextBillion.ai’s Navigation SDKs for Android and iOS. You will  learn how to set up the SDKs, download regional maps and routing data, configure routing modes and test offline functionality to prepare your driver app for journeys beyond network coverage.

Before You Begin: Integration Prerequisites

Before integrating offline navigation, users need to prepare your development environment and identify the regions your drivers will need to navigate without connectivity.

Here’s what you will need:

• A valid NextBillion.ai API Key: You can say get your NB API key from here. Review the platform-specific Navigation SDK and Maps SDK requirements for your Android or iOS project.
• A region for your first test: Choose a small service area and a sample journey within it to make initial downloads and testing easier.
• Internet access for preparation: Download the required regional data while connected, before testing navigation offline.
• Sufficient device storage: Check the estimated download sizes and available storage for your selected regions.
• Location access: Enable location services and grant the necessary permissions so your app can determine the driver’s position.

Your app needs both map tiles to display maps and routing data to calculate routes and support navigation. These datasets are managed separately, so confirm that both are downloaded and ready before starting an offline journey.

Also Read: Navigation Beyond Connectivity: Introducing NextBillion.ai Offline Navigation

Step 1: Install and Initialize the Navigation SDK

Before your app can download regional maps and calculate routes offline, you’ll need to set up the NextBillion.ai Navigation SDK. Follow the steps for your platform below.

For Android

1. Install the SDK: Add the offline-capable Navigation SDK to your app’s Gradle configuration and sync the project. The compatible Maps SDK comes with it.
2. Set up the Maps SDK: When your app starts, initialize the Maps SDK with your NextBillion.ai access key and select NGLTomTom, the tile server required for offline maps.
3. Choose your runtime settings: Set the routing mode your app should start with and the network policy it should use for downloads. Do this before downloading a region or requesting a route.
4. Initialize offline navigation:  Once the Maps SDK is ready, call NBNavigation.initialize(). Wait for the success callback before continuing, and handle any errors through the error callback. Set up the location and foreground service permissions your app needs for navigation

For Gradle dependencies and code examples, see the Android Offline Navigation setup guide.

For iOS

1. Install the SDK: Add the NextBillion Navigation package through Swift Package Manager. It includes the navigation and mapping components you’ll need.
2. Set your access key: Assign your NextBillion.ai access key to NGLAccountManager.accessToken before using the SDK.
3. Choose your runtime settings: Use NBNavigation.NavigationRuntimeConfig to set the initial routing mode and download network policy.
4. Initialize offline navigation: Call NBNavigation.initializeOffline() when your app starts. Handle any initialization errors before moving on to regional downloads.

For implementation examples, see the iOS Offline Navigation setup guide.

Once initialization succeeds, load the region catalog and download the maps and routing data for your first offline trip.

Step 2: Load the Region Catalog and Select a Region

While your device is still online, you can open your app’s offline regions screen. For your first test, choose a region that includes both map tiles and routing data. Make sure it covers every road you plan to use, including your detour.

 For Android:  Start by calling `NBNavigation.fetchRegionLists(country, callback)` with the full English name of a supported country. This shows which regions are already cached. To load the catalog for the first time or refresh it, call `NBNavigation.syncRegions` with `RegionListSyncMode.AUTO`, then fetch the list again. Choose a region where both `hasRoute` and `hasMap` are true.

See the Android Region Catalog Guide here. 

For iOS: Call `NBNavigation.syncOfflineRegionList(syncMode: .auto)` to sync the catalog. Then use `NBNavigation.fetchRegionLists(countries:)` to read the combined list, passing the full English country name in `countries`. Choose a region that contains both `routeRegion` and `mapRegion`.

See the iOS Region Catalog Guide here. 

Show the region’s display name and estimated download size before the driver taps **Download**. Use the selected `regionId` to start the download and track its progress. If a catalog refresh fails, keep any cached regions visible and let the driver retry the part of the refresh that failed.

Step 3: Download and Verify Both Datasets

Before you start the download, subscribe to progress updates. Show the road network data and map tiles separately on the download screen so drivers can see when each is ready.

For Android

When the download screen opens, call NBNavigation.beginDownloadPage. Subscribe to updates with NBNavigation.observeOfflineProgress, then start the download with NBNavigation.downloadRegion(regionId, callback). Mark the region as ready when both routeNetwork and mapTile report COMPLETED.

When the screen closes, cancel the progress subscription and call NBNavigation.endDownloadPage with the same lifecycle owner you passed to NBNavigation.beginDownloadPage.

 Android regional downloads · Android progress states

For iOS

Subscribe with NBNavigation.observeOfflineRegionProgress, then start the download with NBNavigation.downloadRegion(regionId:onProgress:). Each progress update includes the status of both routeNetwork and mapTile.

To confirm the region is ready from the region list, check that routeRegion?.isDownloaded == true and mapInstalledRegion?.allPackagesOk == true. Cancel the progress subscription when the screen closes.

 iOS regional downloads · iOS progress states

If Wi-Fi drops during a download, show the driver which part still needs to finish. When the connection returns, check the latest progress and give the driver the option to resume incomplete work  with NBNavigation.resumeRegion on Android or NBNavigation.resumeRegionDownload on iOS. Android download controls · iOS download controls

Step 4: Choose a Routing Mode

Once the region is ready, run your first test in Offline only mode. Set RouteMode.OFFLINE_ONLY on Android or .offlineOnly on iOS. The SDK calculates the route on the device using the downloaded road network.

After you confirm that routing works offline, switch to Smart mode with RouteMode.SMART on Android or .smart on iOS. Test a trip that passes in and out of coverage to see how the SDK chooses a routing source based on connectivity and the data available on the device.

Use Online only (RouteMode.ONLINE_ONLY on Android or .onlineOnly on iOS) when every route request should go to the online service.

With Online preferred (RouteMode.ONLINE_PREFERRED on Android or .onlinePreferred on iOS), the SDK tries the online service first and can fall back to local routing when the required data is available. Offline preferred (RouteMode.OFFLINE_PREFERRED on Android or .offlinePreferred on iOS) tries local routing first and can fall back to the online service when the device is connected.

For Android

Set the mode with NBNavigation.setRuntimeConfig and pass your current download network policy.

NBNavigation.setRuntimeConfig(

    RouteMode.OFFLINE_ONLY,

    NBNavigation.getDownloadNetworkPolicy()

For iOS

Set RoutingConfig(mode: .offlineOnly) in your runtime configuration. This example limits downloads to Wi-Fi.

let config = NBNavigation.NavigationRuntimeConfig(

    routing: RoutingConfig(mode: .offlineOnly),

    offlineDownloadNetworkPolicy: .wifiOnly

NBNavigation.setNavigationRuntimeConfig(config)

Step 5: Calculate a Route and Start Turn-by-Turn Guidance

Start with a short car route using the coordinates you saved earlier. Both stops and the roads between them need to be within downloaded road-network coverage. If your app gets stops from a dispatch system, save their coordinates on the device before the driver leaves coverage.

For Android

Call NBNavigation.fetchRoute with the origin, destination, language and an NBNavigation.SourceAwareRoutingCallback. Record the RouteSource from the callback so you can verify where the route was calculated. Preview the returned routes, then pass the selected DirectionsRoute to NavLauncherConfig.builder and start guidance with NavigationLauncher.startNavigation once the app has location permission. Android route requests · Android navigation example

For iOS

Create NavigationRouteOptions with the saved waypoints and the car profile. Call try await NBNavigation.fetchRoute(options: options) and check result.source. Call NBNavigation.makeNavigationService with result.routes and the selected route index. Pass the service to NavigationViewController through NavigationOptions to keep rerouting aligned with the SDK’s routing configuration. iOS route requests · iOS navigation example

If your iOS app has a custom map preview, register its active style with NBNavigation.registerOfflineMapStyle before checking the downloaded tiles. iOS offline map preview

Step 6: Test With the Device Offline

On a test device, turn on airplane mode and confirm Wi-Fi is off. Keep location services enabled. Run these checks on Android and iOS.

Then repeat the detour test in Smart mode. Start guidance while connected, turn off mobile data and Wi-Fi mid-trip, and go off route within the downloaded region. Verify that guidance continues and that the app calculates the detour using local routing data. Reconnect and check the reported source on a fresh route request. Android routing behavior · iOS routing behavior

If you see a route line on a blank map, check the installed map package and the active map style. If the map loads and the route request fails, check that the offline engine initialized successfully and that the road-network data covers the full route.

Prepare for a Fleet Rollout

• Plan downloads around actual routes. Check the roads between stops, especially where journeys cross region boundaries. Use the SDK’s along-route recommendations to help drivers identify which regions to download before dispatch. Android region recommendations · iOS region recommendations
• Show readiness before departure. Flag missing or incomplete regions on the trip screen while the driver still has a connection. Test an interrupted download and check that the driver can resume it when the connection returns.
• Keep both datasets current. Refresh the catalogs while connected and check for routing and map updates separately. Give drivers time to install updates before the next trip. Android regional updates · iOS regional updates
• Pilot with the vehicles and devices your fleet uses. Repeat the offline routing and detour tests with the vehicle profiles and supported routing options you plan to deploy. Android route options · iOS vehicle options example

Try Your First Offline Trip

Pick a route where your drivers regularly lose signal. Download the maps and routing data for the full trip, then test a missed turn within the downloaded area while the device is offline. Check that the map stays visible and the app calculates a new route and guides the driver to the next stop.

Save that route and detour as a repeatable test for future driver app releases. To get started, run the trip in a NextBillion.ai reference app, then repeat it in your own integration before rolling it out to drivers.

Android reference app | iOS reference app

Ready to add offline navigation to your driver app? Reach out to our technical team to learn more about NextBillion.ai Offline Navigation and get started with your integration.