Офлайн карты

MapKit SDK осуществляет загрузку данных о карте по сети интернет для отображения на устройстве пользователя. С помощью механизма офлайн-кэшей, MapKit SDK позволяет осуществить предварительную загрузку офлайн-карт, чтобы затем использовать их при отсутствии подключения к интернету.

В офлайн-режиме MapKit SDK предоставляет следующий функционал для загруженных регионов:

• отображение тайлов карты;
• построение автомобильных маршрутов без учета пробок;
• геосаджест и поиск.

РегионыРегионы

Карта в MapKit SDK делится на отдельные регионы, каждому из них соответствует набор данных, которые можно загрузить и использовать в качестве офлайн-кэшей.

Регионами могут быть:

• города: Москва, Минск, Казань и т.д.;
• областные регионы, которые включают в себя несколько городов: Московская область, Минская область и т.д.;
• отдельные страны: Сербия, Финляндия, Армения и т.д.

В MapKit SDK регион описывается классом Region и предоставляет следующие данные:

• id - уникальный идентификатор региона;
• name - название региона;
• center - координаты центра региона;
• size - размер в байтах для скачивания данных этого региона;
• releaseTime - временная метка, когда офлайн карты для данного региона были последний раз обновлены на сервере;
• parentId - идентификатор родительского региона, например: Москва в качестве родительского региона содержит Московскую область.

Получение списка регионовПолучение списка регионов

Точкой входа в API управления офлайн-кэшами является класс OfflineCacheManager. Экземпляр этого класса хранится в виде синглтона в MapKit SDK. Для его получения используется метод MapKit.getOfflineCacheManager.

val offlineCacheManager = MapKitFactory.getInstance().offlineCacheManager

Для получения списка всех доступных регионов используется подписка на событие обновления списка регионов с помощью интерфейса RegionListUpdatesListener.

val listener = RegionListUpdatesListener {
    val regions = offlineCacheManager.regions()
    // Handle regions update
}

offlineCacheManager.addRegionListUpdatesListener(listener)

C помощью метода OfflineCacheManager.regions можно получить список обновленных регионов.

Состояние регионаСостояние региона

Состояние региона описывается перечислением RegionState:

• available - офлайн-карты данного региона доступны для загрузки;
• downloading - офлайн-карты в процессе загрузки;
• paused - процесс загрузки был приостановлен и может быть возобновлен;
• completed - загрузка данных завершена успешно;
• outdated - на сервере есть более новая версия офлайн-карт для данного региона;
• unsupported - офлайн-карты данного региона загружены, но больше не поддерживаются, после их удаления с устройства регион пропадет из доступных для загрузки;
• need_update - данные сильно устарели, требуется загрузить новую версию.

Для получения текущего состояния для отдельного региона используется метод OfflineCacheManager.getState.

MapKit SDK предоставляет возможность подписаться на события изменения состояния регионов с помощью интерфейса RegionListener. Он предоставляет два метода для переопределения:

1. RegionListener.onRegionStateChanged - оповещает об изменении состояния отдельного региона.
2. RegionListener.onRegionProgress - оповещает об изменении статуса загрузки офлайн-карты региона.

val regionListener = object : RegionListener {
    override fun onRegionStateChanged(regionId: Int) {
        val state = offlineCacheManager.getState(regionId)
        // Handle region state changes
    }

    override fun onRegionProgress(regionId: Int) {
        val progress = offlineCacheManager.getProgress(regionId)
        // Handle region progress changes
    }
}

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.

Обработка ошибокОбработка ошибок

В ходе загрузки происходит скачивание данных офлайн-карт с сервера и сохранения офлайн-кэшей на диске устройства. Для обработки различных ошибок, которые могут произойти в ходе данного процесса, используется интерфейс OfflineCacheManager.ErrorListener.

val listener = object : ErrorListener {
    override fun onError(error: Error) {
        when (error) {
            is LocalError -> {
                // Handle local error
            }
            is RemoteError -> {
                // Handle remote error
            }
            else -> { // Undefined error }
        }
    }

    override fun onRegionError(error: Error, regionId: Int) {
        // Handle error for region with regionId id
    }
}

Данный интерфейс предоставляет методы для обработки ошибок, связанных с загрузкой определенных регионов и работой OfflineCacheManager.

Ошибки могут быть двух типов:

• LocalError - ошибки на устройстве пользователя, например, повреждение диска, недостаток свободного места для сохранения;
• RemoteError - ошибки со стороны сервера.

Хранение офлайн-кэшейХранение офлайн-кэшей

Данные офлайн-карт, которые были получены во время их загрузки, MapKit SDK сохраняет на диске устройства в специальном формате офлайн-кэшей.

Для получения пути, по которому хранятся офлайн-кэши в файловой системе, используется метод OfflineCacheManager.requestPath.

offlineCacheManager.requestPath { path ->
    // Handle requested path
}

Данный метод принимает в качестве аргумента интерфейс OfflineCacheManager.PathGetterListener, с помощью которого можно подписаться на событие получения пути.

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

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

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

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

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

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