Офлайн карты
MapKit SDK осуществляет загрузку данных о карте по сети интернет для отображения на устройстве пользователя. С помощью механизма офлайн-кэшей, MapKit SDK позволяет осуществить предварительную загрузку офлайн-карт, чтобы затем использовать их при отсутствии подключения к интернету.
В офлайн-режиме MapKit SDK предоставляет следующий функционал для загруженных регионов:
- отображение тайлов карты;
- построение автомобильных маршрутов без учета пробок;
- геосаджест и поиск.
Важно
Функционал офлайн-карт доступен только при наличии платной лицензии.
Регионы
Карта в MapKit SDK делится на отдельные регионы, каждому из них соответствует набор данных, которые можно загрузить и использовать в качестве офлайн-кэшей.
Регионами могут быть:
- города: Москва, Минск, Казань и т.д.;
- областные регионы, которые включают в себя несколько городов: Московская область, Минская область и т.д.;
- отдельные страны: Сербия, Финляндия, Армения и т.д.
В MapKit SDK регион описывается классом OfflineCacheRegion и предоставляет следующие данные:
id
- уникальный идентификатор региона;name
- название региона;center
- координаты центра региона;size
- размер в байтах для скачивания данных этого региона;releaseTime
- временная метка, когда офлайн карты для данного региона были последний раз обновлены на сервере;parentId
- идентификатор родительского региона, например: Москва в качестве родительского региона содержит Московскую область.
Получение списка регионов
Точкой входа в API управления офлайн-кэшами является класс OfflineCacheManager. Экземпляр этого класса хранится в виде синглтона в MapKit SDK. Для его получения используется метод mapkit.offlineCacheManager.
final offlineCacheManager = mapkit.offlineCacheManager;
Для получения списка всех доступных регионов используется подписка на событие обновления списка регионов с помощью интерфейса OfflineMapRegionListUpdatesListener.
final class OfflineCacheRegionListenerImpl implements OfflineMapRegionListUpdatesListener {
@override
void onListUpdated() {
final regions = offlineCacheManager.regions();
// Handle regions update
}
}
final listener = OfflineCacheRegionListenerImpl();
offlineCacheManager.addRegionListUpdatesListener(listener)
C помощью метода OfflineCacheManager.regions можно получить список обновленных регионов.
Состояние региона
Состояние региона описывается перечислением OfflineCacheRegionState:
available
- офлайн-карты данного региона доступны для загрузки;downloading
- офлайн-карты в процессе загрузки;paused
- процесс загрузки был приостановлен и может быть возобновлен;completed
- загрузка данных завершена успешно;outdated
- на сервере есть более новая версия офлайн-карт для данного региона;unsupported
- офлайн-карты данного региона загружены, но больше не поддерживаются, после их удаления с устройства регион пропадет из доступных для загрузки;need_update
- данные сильно устарели, требуется загрузить новую версию.
Для получения текущего состояния для отдельного региона используется метод OfflineCacheManager.getState.
MapKit SDK предоставляет возможность подписаться на события изменения состояния регионов с помощью интерфейса OfflineCacheRegionListener. Он предоставляет два метода для переопределения:
- OfflineCacheRegionListener.onRegionStateChanged - оповещает об изменении состояния отдельного региона.
- OfflineCacheRegionListener.onRegionProgress - оповещает об изменении статуса загрузки офлайн-карты региона.
final class OfflineCacheRegionListenerImpl implements OfflineCacheRegionListener {
@override
void onRegionStateChanged(int regionId) {
final state = offlineCacheManager.getState(regionId);
// Handle region state changes
}
@override
void onRegionProgress(int regionId) {
final progress = offlineCacheManager.getProgress(regionId);
// Handle region progress changes
}
}
final regionListener = OfflineCacheRegionListenerImpl();
offlineCacheManager.addRegionListener(regionListener);
Дополнительная информация о регионах
При помощи следующих методов можно получить дополнительную информацию о регионах:
- OfflineCacheManager.getCities - получение списка из названий городов, которые содержит регион.
- OfflineCacheManager.getDownloadedReleaseTime - дата релиза загруженного региона.
Загрузка офлайн-карт
Для управления статусом загрузки офлайн-карт отдельного региона MapKit SDK предоставляет следующий набор методов:
- OfflineCacheManager.startDownload - начинает загрузку офлайн-карт;
- OfflineCacheManager.stopDownload - если загрузка карт была начата, отменяет ее;
- OfflineCacheManager.pauseDownload - приостанавливает загрузку офлайн-карт;
- OfflineCacheManager.drop - удаляет все офлайн-кэши для отдельного региона.
Совет
Используйте метод OfflineCacheManager.mayBeOutOfAvailableSpace для проверки наличия свободного места на устройстве прежде чем начинать загрузку.
Все методы управления статусом загрузки офлайн-карт принимают единственный аргумент - id региона, для которого применяется указанное действие. В результате выполнения данных методов состояние регионов может измениться. Так, например, если регион доступен для скачивания, то после вызова метода OfflineCacheManager.startDownload начнется его загрузка, и состояние региона изменится на downloading
.
Свойства загрузки
При помощи данных методов можно настроить свойства загрузки офлайн-карт:
- OfflineCacheManager.allowUseCellularNetwork - позволяет включить возможность загрузки и обновления офлайн-карт по мобильной сети (3G, LTE и т.п.).
- OfflineCacheManager.enableAutoUpdate - активирует автоматическое обновление офлайн-кэшей для регионов, которые находятся в состоянии
need_update
.
Обработка ошибок
В ходе загрузки происходит скачивание данных офлайн-карт с сервера и сохранения офлайн-кэшей на диске устройства. Для обработки различных ошибок, которые могут произойти в ходе данного процесса, используется интерфейс OfflineCacheManagerErrorListener.
final class OfflineCacheManagerErrorListenerImpl implements OfflineCacheManagerErrorListener {
@override
void onError(Error error) {
switch (error.runtimeType) {
case LocalError:
// Handle local error
case RemoteError:
// Handle remote error
default:
// Handle undefined error
}
}
@override
void onRegionError(Error error, int regionId) {
// Handle error for region with regionId id
}
}
Данный интерфейс предоставляет методы для обработки ошибок, связанных с загрузкой определенных регионов и работой OfflineCacheManager.
Ошибки могут быть двух типов:
- LocalError - ошибки на устройстве пользователя, например, повреждение диска, недостаток свободного места для сохранения;
- RemoteError - ошибки со стороны сервера.
Хранение офлайн-кэшей
Данные офлайн-карт, которые были получены во время их загрузки, MapKit SDK сохраняет на диске устройства в специальном формате офлайн-кэшей.
Для получения пути, по которому хранятся офлайн-кэши в файловой системе, используется метод OfflineCacheManager.requestPath.
offlineCacheManager.requestPath(
OfflineCacheManagerPathGetterListener(onPathReceived: (path) => /* Handle requested path */)
);
Данный метод принимает в качестве аргумента интерфейс OfflineCacheManagerPathGetterListener, с помощью которого можно подписаться на событие получения пути.
Существует возможность изменить место хранения офлайн-кэшей на устройстве. Для этого предусмотрено два метода:
- OfflineCacheManager.setCachePath - позволяет изменить место на устройстве пользователя, в котором хранятся данные офлайн-кэшей. Если по заданному пути уже есть офлайн-кэши, то они будут использоваться, иначе, будут инициализированы новые кэши.
- OfflineCacheManager.moveData - переносит текущие офлайн-кэши в новое место на устройстве.
С помощью метода OfflineCacheManager.computeCacheSize можно посчитать сколько памяти занимают все офлайн-кэши на устройстве пользователя.
Метод OfflineCacheManager.clear используется для удаления офлайн-кэшей.