Офлайн карты

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

  1. YMKOfflineCacheRegionListener.onRegionStateChanged(withRegionId:) - оповещает об изменении состояния отдельного региона.
  2. 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)

Дополнительная информация о регионах

При помощи следующих методов можно получить дополнительную информацию о регионах:

Загрузка офлайн-карт

Для управления статусом загрузки офлайн-карт отдельного региона MapKit SDK предоставляет следующий набор методов:

Совет

Используйте метод YMKOfflineCacheManager.mayBeOutOfAvailableSpace(withRegionId:) для проверки наличия свободного места на устройстве прежде чем начинать загрузку.

Все методы управления статусом загрузки офлайн-карт принимают единственный аргумент - id региона, для которого применяется указанное действие. В результате выполнения данных методов состояние регионов может измениться. Так, например, если регион доступен для скачивания, то после вызова метода YMKOfflineCacheManager.startDownload(withRegionId:) начнется его загрузка, и состояние региона изменится на downloading.

Свойства загрузки

При помощи данных методов можно настроить свойства загрузки офлайн-карт:

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

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

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

  1. YMKOfflineCacheManager.setCachePathWithPath(_:pathSetterListener:) - позволяет изменить место на устройстве пользователя, в котором хранятся данные офлайн-кэшей. Если по заданному пути уже есть офлайн-кэши, то они будут использоваться, иначе, будут инициализированы новые кэши.
  2. YMKOfflineCacheManager.moveData(withNewPath:dataMoveListener:) - переносит текущие офлайн-кэши в новое место на устройстве.

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

Метод YMKOfflineCacheManager.clear(clearCallback:) используется для удаления офлайн-кэшей.

Исходный код

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

Предыдущая
Построение маршрутов
Следующая
Вступление
В этой статье: