Download Regional Data

Use this section to start regional downloads after binding the download screen lifecycle and choosing the download network policy where each download can include both road-network data and map-tile data for the selected region.

Bind the Download Screen Lifecycle

Call beginDownloadPage() and endDownloadPage(owner) on the main thread, and pass the same owner to both calls. A “Fragment” should use viewLifecycleOwner and clean up in onDestroyView(). An “Activity” can pair the calls in onCreate() and onDestroy().

1
private var progressSubscription:
2
    NBNavigation.OfflineProgressSubscription? = null
3
 
4
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
5
    super.onViewCreated(view, savedInstanceState)
6
    NBNavigation.beginDownloadPage(viewLifecycleOwner, savedInstanceState)
7
    progressSubscription = NBNavigation.observeOfflineProgress {
8
        renderDownloadProgress(it)
9
    }
10
}
11
 
12
override fun onDestroyView() {
13
    progressSubscription?.cancel()
14
    progressSubscription = null
15
    NBNavigation.endDownloadPage(viewLifecycleOwner)
16
    super.onDestroyView()
17
}

Set the Download Network Policy

The default policy is WIFI_ONLY. Set the policy before starting or resuming a download.

1
NBNavigation.setDownloadNetworkPolicy(
2
    OfflineDownloadNetworkPolicy.WIFI_ONLY
3
)

Policy	Behavior
`WIFI_ONLY`	Wi-Fi only. It is the default
`UNMETERED`	Allows Wi-Fi, Ethernet, and other unmetered networks
`ANY`	Allows mobile data. It is recommended to display the download size and obtain user confirmation first.

Start a Download

1

2
NBNavigation.downloadRegion(
3
    regionId,
4
    object : NBNavigationTaskCallback<OfflineRegionDownloadData> {
5
        override fun onSuccess(result: OfflineRegionDownloadData?) {
6
            if (result == null) return
7
            Log.i("OfflineNavigation", "route=${result.routeRegion.downloadStatus}, " +
8
                "map=${result.mapTileRegion.action}")
9
        }
10
        override fun onError(throwable: Throwable) {
11
            Log.e("OfflineNavigation", "downloadRegion failed", throwable)
12
        }
13
    }
14
)

The SDK submits the map task first and then performs the road-network download. A successful callback means that request orchestration completed. It does not mean that the map download finished. If the road-network operation fails, the map task may still be active. Use observeOfflineProgress() as the source of truth for final state.

Result field	Meaning	Application use
`regionId`	Requested catalog region	Associate the response with the UI row
`routeRegion.downloadStatus`	IDLE, DOWNLOADING, COMPLETE, PARTIAL, FAILED, PAUSED, or UNKNOWN	Use the enum for the immediate route-side state
`routeRegion.tilesDone` / `tilesTotal`	Route tiles available after this run	Show route-side completion when the total is valid
`routeRegion.downloadSuccessCount` / `downloadFailedCount`	Tile requests that succeeded or failed during this run	Diagnostics only. Use observed progress for the final UI state
`routeRegion.skipped` / `interrupted` / `interruptReason`	Whether duplicate work was skipped or this native run stopped early	Refresh progress before deciding whether to resume or retry
`routeRegion.autoRetryAttempts` / `completedAfterAutoRetry`	SDK-managed retry summary	Useful for diagnostics. Do not schedule an unbounded second retry loop
`routeRegion.errorCode`	Native route error; 0 means none reported	Record for diagnostics. Do not parse message text
`mapTileRegion.action`	ENQUEUED, RESUMED, ALREADY_COMPLETED, or ALREADY_IN_PROGRESS	Use this enum for application logic
`mapTileRegion.message`	Human-readable diagnostic text	Display or log only. Not a stable status code

Submitting the same regionId again does not create a duplicate active map task. Use resumeRegion() for paused, failed, or partially completed work. Always refresh observed progress after either a success or an error callback.