Офлайн карты

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. Он предоставляет два метода для переопределения:

1. OfflineCacheRegionListener.onRegionStateChanged - оповещает об изменении состояния отдельного региона.
2. 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 - удаляет все офлайн-кэши для отдельного региона.

Все методы управления статусом загрузки офлайн-карт принимают единственный аргумент - 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, с помощью которого можно подписаться на событие получения пути.

Существует возможность изменить место хранения офлайн-кэшей на устройстве. Для этого предусмотрено два метода:

1. OfflineCacheManager.setCachePath - позволяет изменить место на устройстве пользователя, в котором хранятся данные офлайн-кэшей. Если по заданному пути уже есть офлайн-кэши, то они будут использоваться, иначе, будут инициализированы новые кэши.
2. OfflineCacheManager.moveData - переносит текущие офлайн-кэши в новое место на устройстве.

С помощью метода OfflineCacheManager.computeCacheSize можно посчитать сколько памяти занимают все офлайн-кэши на устройстве пользователя.

Метод OfflineCacheManager.clear используется для удаления офлайн-кэшей.

Исходный кодИсходный код

Подробнее с примерами использования API офлайн карт из MapKit SDK можно ознакомиться в демо-приложении map_offline в нашем репозитории на GitHub.