Offline maps

The MapKit SDK downloads maps over the internet so they can be shown on user devices. Using an offline caching process, the MapKit SDK downloads maps in advance so they can be used later when there's no internet connection.

The MapKit SDK's offline mode comes with the following features:

• Displaying map tiles.
• Building routes for cars (without traffic data).
• Geosuggest and search.

RegionsRegions

In the MapKit SDK, maps are divided into regions, each of which is associated with a set of data you can download and cache offline.

Regions can be:

• City regions that include multiple localities (Jizan Region, Najran Region).
• Countries (Azerbaijan, Israel).

In the MapKit SDK, regions are described by a MMKOfflineCacheRegion class and provide the following data:

• id: The region's unique ID.

• name: The region's name.

• center: The coordinates of the region center.

• size: The download size of the region (in bytes).

• releaseTime: The timestamp for when offline maps for this region were last updated on the server.

• parentId: The ID of the parent region. For example, Al Baha as the parent region contains Al Bahah Region.

Getting a list of regionsGetting a list of regions

The MMKOfflineCacheManager class is the entry point for the offline cache management API. An instance of this class is stored as a singleton in the MapKit SDK. To get it, use the MMKMapKit.offlineCacheManager method.

let offlineCacheManager = MMKMapKit.sharedInstance().offlineCacheManager

To get the list of all available regions, use the subscription to the region list update event in the MMKOfflineMapRegionListUpdatesListener interface.

class RegionListUpdatesListener: NSObject, MMKOfflineMapRegionListUpdatesListener {
    func onListUpdated() {
        let regions = offlineCacheManager.regions()
        // Handle regions update
    }
}

let regionListUpdatesListener = RegionListUpdatesListener()
offlineCacheManager.addRegionListUpdatesListener(with: regionListUpdatesListener)

You can get a list of updated regions using the MMKOfflineCacheManager.regions() method.

Region stateRegion state

Region states are described by the MMKOfflineCacheRegionState list:

• available: The region's offline maps are available for download.
• downloading: Offline maps are being downloaded.
• paused: The download was paused and can be resumed.
• completed: The data is downloaded.
• outdated: The server has an updated version of the offline maps for this region.
• unsupported: The offline maps of the region are downloaded but no longer supported. If they are deleted from the device, the region will no longer be available for download.
• need_update: Data outdated, download the new version.

To get the current state for a particular region, use the MMKOfflineCacheManager.getStateWithRegionId(_:) method.

You can use the MapKit SDK to subscribe to region state change events in the MMKOfflineCacheRegionListener interface. There are two options:

1. MMKOfflineCacheRegionListener.onRegionStateChanged(withRegionId:): A particular region's state change.
2. MMKOfflineCacheRegionListener.onRegionProgress(withRegionId:): A state change for a region's offline map.

class RegionListener: NSObject, MMKOfflineCacheRegionListener {
    func onRegionStateChanged(withRegionId regionId: UInt) {
        let state = offlineCacheManager.getStateWithRegionId(regionId)
        // Handle region state changes
    }

    func onRegionProgress(withRegionId regionId: UInt) {
        let progress = offlineCacheManager.getProgressWithRegionId(regionId)
        // Handle region progress changes
    }
}

let regionListener = RegionListener()
offlineCacheManager.addRegionListener(regionListener)

Additional information about regionsAdditional information about regions

You can get additional information about regions using the following methods:

• MMKOfflineCacheManager.getCitiesWithRegionId(_:): Getting a list of the names of cities in the region.
• MMKOfflineCacheManager.getDownloadedReleaseTime(withRegionId:): Release date for the downloaded region.

Downloading mapsDownloading maps

The MapKit SDK provides the following methods for managing the download state of a region's offline maps.

• MMKOfflineCacheManager.startDownload(withRegionId:): Starts downloading offline maps.
• MMKOfflineCacheManager.stopDownload(withRegionId:): Cancels ongoing map downloads.
• MMKOfflineCacheManager.pauseDownload(withRegionId:): Pauses map downloads.
• MMKOfflineCacheManager.drop(withRegionId:): Deletes all offline caches for the region.

All methods for managing offline map download states take a single argument: the ID of the region the action applies to. The region state may change when a method is executed. For example, if a region is available for download, the download starts after calling the MMKOfflineCacheManager.startDownload(withRegionId:) method, and the region's state changes to downloading.

Downloading propertiesDownloading properties

These methods let you configure offline map download properties:

• MMKOfflineCacheManager.allowUseCellularNetwork(withUseCellular:): Used to enable uploading and updating for offline maps over mobile networks (3G, LTE, and so on).
• MMKOfflineCacheManager.enableAutoUpdate(withEnable:): Activates automatic updating for offline caches in regions with the need_update state.

Error handlingError handling

Offline map data is downloaded from the server, and offline caches are saved to the device. The MMKOfflineCacheManagerErrorListener interface is used to handle errors that may appear in the process.

class ErrorListener: NSObject, MMKOfflineCacheManagerErrorListener {
    func onErrorWithError(_ error: Error) {
        switch error {
        case let localError as MRTLocalError:
            // Handle local error
        case let remoteError as MRTRemoteError:
            // Handle remote error
        default:
            // Undefined error
        }
    }

    func onRegionErrorWithError(_ error: Error, regionId: UInt) {
        // Handle error for region with regionId id
    }
}

This interface provides methods for handling errors related to downloading particular regions and MMKOfflineCacheManager.

There are two types of errors:

• MRTLocalError: Errors on the user's device, such as a damaged disk or insufficient space.
• MRTRemoteError: Errors on the server side.

Storing offline cachesStoring offline caches

The MapKit SDK saves maps downloaded to the device's disk in a special offline cache format.

To get the path for the offline cache storage in the file system, the MMKOfflineCacheManager.requestPath(pathGetterListener:) method is used.

offlineCacheManager.requestPath { path in
    // Handle requested path
}

This method takes the MMKOfflineCacheManagerPathGetterListener interface used to subscribe to the event where the path is obtained as an argument.

The cache storage on the device may be changed. There are two methods used for that:

1. MMKOfflineCacheManager.setCachePathWithPath(_:pathSetterListener:): Used to change the location of cached data on the user's device. If there are already caches stored at the path set, they will be used, with new caches initiated otherwise.
2. MMKOfflineCacheManager.moveData(withNewPath:dataMoveListener:): Moves current caches to a new location on the device.

The MMKOfflineCacheManager.computeCacheSize(sizeCallback:) method calculates how much memory all caches are taking up on the user's device.

The MMKOfflineCacheManager.clear(clearCallback:) method is used to delete caches.

Source codeSource code

As an example of using the offline maps API functionality, see the MapOffline app in our GitHub repository.