Офлайн карты
MapKit SDK осуществляет загрузку данных о карте по сети интернет для отображения на устройстве пользователя. С помощью механизма офлайн-кэшей, MapKit SDK позволяет осуществить предварительную загрузку офлайн-карт, чтобы затем использовать их при отсутствии подключения к интернету.
В офлайн-режиме MapKit SDK предоставляет следующий функционал для загруженных регионов:
- отображение тайлов карты;
- построение автомобильных маршрутов без учета пробок;
- геосаджест и поиск.
Важно
Функционал офлайн-карт доступен только при наличии платной лицензии.
Регионы
Карта в MapKit SDK делится на отдельные регионы, каждому из них соответствует набор данных, которые можно загрузить и использовать в качестве офлайн-кэшей.
Регионами могут быть:
- города: Москва, Минск, Казань и т.д.;
- областные регионы, которые включают в себя несколько городов: Московская область, Минская область и т.д.;
- отдельные страны: Сербия, Финляндия, Армения и т.д.
В MapKit SDK регион описывается классом YMKOfflineCacheRegion и предоставляет следующие данные:
id
- уникальный идентификатор региона;name
- название региона;center
- координаты центра региона;size
- размер в байтах для скачивания данных этого региона;releaseTime
- временная метка, когда офлайн карты для данного региона были последний раз обновлены на сервере;parentId
- идентификатор родительского региона, например: Москва в качестве родительского региона содержит Московскую область.
Получение списка регионов
Точкой входа в API управления офлайн-кэшами является класс YMKOfflineCacheManager. Экземпляр этого класса хранится в виде синглтона в MapKit SDK. Для его получения используется метод YMKMapKit.offlineCacheManager.
let offlineCacheManager = YMKMapKit.sharedInstance().offlineCacheManager
Для получения списка всех доступных регионов используется подписка на событие обновления списка регионов с помощью интерфейса YMKOfflineMapRegionListUpdatesListener.
class RegionListUpdatesListener: NSObject, YMKOfflineMapRegionListUpdatesListener {
func onListUpdated() {
let regions = offlineCacheManager.regions()
// Handle regions update
}
}
let regionListUpdatesListener = RegionListUpdatesListener()
offlineCacheManager.addRegionListUpdatesListener(with: regionListUpdatesListener)
C помощью метода YMKOfflineCacheManager.regions() можно получить список обновленных регионов.
Состояние региона
Состояние региона описывается перечислением YMKOfflineCacheRegionState:
available
- офлайн-карты данного региона доступны для загрузки;downloading
- офлайн-карты в процессе загрузки;paused
- процесс загрузки был приостановлен и может быть возобновлен;completed
- загрузка данных завершена успешно;outdated
- на сервере есть более новая версия офлайн-карт для данного региона;unsupported
- офлайн-карты данного региона загружены, но больше не поддерживаются, после их удаления с устройства регион пропадет из доступных для загрузки;need_update
- данные сильно устарели, требуется загрузить новую версию.
Для получения текущего состояния для отдельного региона используется метод YMKOfflineCacheManager.getStateWithRegionId(_:).
MapKit SDK предоставляет возможность подписаться на события изменения состояния регионов с помощью интерфейса YMKOfflineCacheRegionListener. Он предоставляет два метода для переопределения:
- YMKOfflineCacheRegionListener.onRegionStateChanged(withRegionId:) - оповещает об изменении состояния отдельного региона.
- YMKOfflineCacheRegionListener.onRegionProgress(withRegionId:) - оповещает об изменении статуса загрузки офлайн-карты региона.
class RegionListener: NSObject, YMKOfflineCacheRegionListener {
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)
Дополнительная информация о регионах
При помощи следующих методов можно получить дополнительную информацию о регионах:
- YMKOfflineCacheManager.getCitiesWithRegionId(_:) - получение списка из названий городов, которые содержит регион.
- YMKOfflineCacheManager.getDownloadedReleaseTime(withRegionId:) - дата релиза загруженного региона.
Загрузка офлайн-карт
Для управления статусом загрузки офлайн-карт отдельного региона MapKit SDK предоставляет следующий набор методов:
- YMKOfflineCacheManager.startDownload(withRegionId:) - начинает загрузку офлайн-карт;
- YMKOfflineCacheManager.stopDownload(withRegionId:) - если загрузка карт была начата, отменяет ее;
- YMKOfflineCacheManager.pauseDownload(withRegionId:) - приостанавливает загрузку офлайн-карт;
- YMKOfflineCacheManager.drop(withRegionId:) - удаляет все офлайн-кэши для отдельного региона.
Совет
Используйте метод YMKOfflineCacheManager.mayBeOutOfAvailableSpace(withRegionId:) для проверки наличия свободного места на устройстве прежде чем начинать загрузку.
Все методы управления статусом загрузки офлайн-карт принимают единственный аргумент - id региона, для которого применяется указанное действие. В результате выполнения данных методов состояние регионов может измениться. Так, например, если регион доступен для скачивания, то после вызова метода YMKOfflineCacheManager.startDownload(withRegionId:) начнется его загрузка, и состояние региона изменится на downloading
.
Свойства загрузки
При помощи данных методов можно настроить свойства загрузки офлайн-карт:
- YMKOfflineCacheManager.allowUseCellularNetwork(withUseCellular:) - позволяет включить возможность загрузки и обновления офлайн-карт по мобильной сети (3G, LTE и т.п.).
- YMKOfflineCacheManager.enableAutoUpdate(withEnable:) - активирует автоматическое обновление офлайн-кэшей для регионов, которые находятся в состоянии
need_update
.
Обработка ошибок
В ходе загрузки происходит скачивание данных офлайн-карт с сервера и сохранения офлайн-кэшей на диске устройства. Для обработки различных ошибок, которые могут произойти в ходе данного процесса, используется интерфейс YMKOfflineCacheManagerErrorListener.
class ErrorListener: NSObject, YMKOfflineCacheManagerErrorListener {
func onErrorWithError(_ error: Error) {
switch error {
case let localError as YRTLocalError:
// Handle local error
case let remoteError as YRTRemoteError:
// Handle remote error
default:
// Undefined error
}
}
func onRegionErrorWithError(_ error: Error, regionId: UInt) {
// Handle error for region with regionId id
}
}
Данный интерфейс предоставляет методы для обработки ошибок, связанных с загрузкой определенных регионов и работой YMKOfflineCacheManager.
Ошибки могут быть двух типов:
- YRTLocalError - ошибки на устройстве пользователя, например, повреждение диска, недостаток свободного места для сохранения;
- YRTRemoteError - ошибки со стороны сервера.
Хранение офлайн-кэшей
Данные офлайн-карт, которые были получены во время их загрузки, MapKit SDK сохраняет на диске устройства в специальном формате офлайн-кэшей.
Для получения пути, по которому хранятся офлайн-кэши в файловой системе, используется метод YMKOfflineCacheManager.requestPath(pathGetterListener:).
offlineCacheManager.requestPath { path in
// Handle requested path
}
Данный метод принимает в качестве аргумента интерфейс YMKOfflineCacheManagerPathGetterListener, с помощью которого можно подписаться на событие получения пути.
Существует возможность изменить место хранения офлайн-кэшей на устройстве. Для этого предусмотрено два метода:
- YMKOfflineCacheManager.setCachePathWithPath(_:pathSetterListener:) - позволяет изменить место на устройстве пользователя, в котором хранятся данные офлайн-кэшей. Если по заданному пути уже есть офлайн-кэши, то они будут использоваться, иначе, будут инициализированы новые кэши.
- YMKOfflineCacheManager.moveData(withNewPath:dataMoveListener:) - переносит текущие офлайн-кэши в новое место на устройстве.
С помощью метода YMKOfflineCacheManager.computeCacheSize(sizeCallback:) можно посчитать сколько памяти занимают все офлайн-кэши на устройстве пользователя.
Метод YMKOfflineCacheManager.clear(clearCallback:) используется для удаления офлайн-кэшей.
Исходный код
Подробнее с примерами использования API офлайн карт из MapKit SDK можно ознакомиться в демо-приложении MapOffline
в нашем репозитории на GitHub.