Lifecycle and App Upgrades

Closing a Screen

Closing the screen does not stop region downloads automatically. To pause or cancel a download, call the corresponding region-control method explicitly.

Cancel progressSubscription to stop screen-level observation.
Call endDownloadPage to release ownership of the offline map screen.
Do not call shutdownOffline when closing a screen, ending one navigation session, or moving the app to the background.

Shutting Down the Offline Subsystem

Infrequent lifecycle operation:

1
// Call only when ending the entire offline subsystem lifecycle.
2

3
await NBNavigation.shutdownOffline()
4

5
//Reinitialize before using an offline API again.
6

7
try await NBNavigation.initializeOffline()

shutdownOffline stops shared progress observation, releases download-screen ownership, cancels native activity, and releases engine resources. It does not delete offline region data from disk. Normal app lifecycles usually do not need to call it.

App Upgrades and Data Retention

Scenario	Offline-data result	Requirement
In-place update with the same Bundle ID	The sandbox is normally preserved and the default offline directory remains available	Keep the Bundle ID unchanged and do not delete data programmatically
Uninstall and reinstall	The system deletes the app sandbox and offline data is lost	The app must clearly prompt the user to download the data again
Change the Bundle ID or signing container	The app uses a new sandbox container	Treat as a new installation
Custom dataRoot location changes	Existing data remains in the previous directory and the new engine cannot read it	Derive the same subdirectory from Application Support on every launch
Call deleteRegionAllData	Routing and map data for the region is deleted	Trigger only in response to an explicit user action

Upgrade requirement

Leave dataRoot unset whenever possible so SDK 4.0.0 resolves the default directory from “Application Support” on every launch. If a custom location is required, resolve “Application Support” again on every launch and append a fixed subdirectory. Do not persist in an absolute sandbox path. The SDK performs supported database migrations during initialization. The app must not modify database files or schema_version.