Map Download lifecycle

In this guide we are going to cover the offline maps download life-cycle and how to monitor statuses. The SDK prepares the shared Preview Bundle and regional packages in parallel. Call beginDownloadPage(withOwner:) when the download screen appears and endDownloadPage() when it closes. This lets the SDK prepare shared preview resources early while keeping screen ownership bound to the active UI.

1
final class RegionalOfflineDownloadViewController: UIViewController {
2
 
3
    override func viewWillAppear(_ animated: Bool) {
4
        super.viewWillAppear(animated)
5
        NGLRegionalOffline.beginDownloadPage(withOwner: self)
6
    }
7
 
8
    override func viewWillDisappear(_ animated: Bool) {
9
        super.viewWillDisappear(animated)
10
 
11
        if isMovingFromParent || navigationController?.isBeingDismissed == true {
12
            NGLRegionalOffline.endDownloadPage()
13
        }
14
    }
15
}

A task can remain in .preparingOfflineDisplay at up to 99% while the SDK prepares preview resources. The task reaches 100% only after the preview style, TileJSON/source, glyphs, sprites, and preview database have been validated and applied to the map engine.

Observe shared preview resource status

1
private var importToken: NGLRegionalOfflineListenerToken?
2
 
3
func observePreviewResources() {
4
    importToken = NGLRegionalOffline.addPreviewBundleImportStatusListener {
5
        [weak self] status in
6
        guard let self else { return }
7
 
8
        if status.previewBundleReady {
9
            statusLabel.text = "Offline resources are ready"
10
        } else if status.waitingForNetwork {
11
            statusLabel.text = "Waiting for a network connection"
12
        } else if status.ensuring {
13
            statusLabel.text = "Preparing offline resources"
14
        } else if let message = status.lastErrorMessage {
15
            statusLabel.text = message
16
        }
17
    }
18
}

Read the current status synchronously when needed:

1
let status = NGLRegionalOffline.previewBundleImportStatusSync()
2
let previewResourcesAreReady = status.previewBundleReady

Remove the listener when it is no longer needed:

1
func removePreviewResourceObserver() {
2
    if let importToken {
3
        NGLRegionalOffline.removePreviewBundleImportStatusListener(importToken)
4
        self.importToken = nil
5
    }
6
}