Manage Downloads
This guide lists SDK download controls to pause, resume, cancel, or delete region tasks, and recommendations for applying clear UI states for paused, failed, and deletion flows.
To pause a download task:
To resume a paused or failed task from its checkpoint:
To cancel (stop) a download task:
To delete a download task and asynchronously delete the region’s installed data:
| Action | Behavior |
|---|---|
| PAUSE | Stop the current transfer while retaining the task and checkpoint |
| RESUME | Resume a paused or failed task from its checkpoint; when offline, remain in PAUSED_NETWORK |
| CANCEL | Cancel the task and remove its queue record without deleting an already installed region |
| DELETE | Cancel the task for the same region and asynchronously delete the region's installed data and engine path |
Please note that the above control methods must be called on the main thread
DELETE currently has no separate completion callback. Before deleting a region, clearly tell the user that the installed offline map data for that region will be removed. After calling DELETE, disable duplicate delete actions and confirm the result after the local region list refreshes. Do not delete SDK database files directly as doing so can make the manifest, open handles, and actual files inconsistent.
Concurrency, Threading, and Lifecycle
Use this section to understand which Offline Maps APIs must run on the main thread, which APIs can perform disk or network work, and how page lifecycle ownership affects active sessions and listeners.
| API | Invocation constraint |
|---|---|
| beginDownloadPage(), endDownloadPage(owner) | Main thread |
| controlDownload(), setDownloadForegroundHook() | Main thread |
| focusPreviewRegion() | Main thread, after the map has been created |
| Add/remove Java progress listeners | Main thread |
| download(), queryRegions(), fetchRegionList(), fetchRegionDetail() | suspend APIs; the SDK dispatches internally to IO |
| loadOfflineDetail(), offlinePreviewResourceStatus() | Worker thread |
| listInstalledRegions(), hasInstalledOfflineRegions() | Return only a cached snapshot on the main thread; perform a complete cold-start read on a worker thread |
| previewBundleImportStatus(), queueRecordFor() | Current in-memory or persisted queue snapshot; may be called immediately |
Other constraints:
-
A maximum of three region tasks run concurrently; remaining tasks are queued.
-
A region task may contain any number of pre-generated packages.
-
Download progress is aggregated at the region level. Do not create a separate product task for each package.
-
Kotlin UI should use repeatOnLifecycle to collect Flows. Java UI should remove listeners according to the page lifecycle.
-
The SDK singleton retains only the application context. Page sessions and owner-bound listeners are released automatically when the owner is destroyed.