Перейти к основному содержимому

iOS SDK

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

Примеры использования SDK см. в разделе Примеры. Описание всех классов и методов см. в разделе Справочник API.

Картографические данные поддерживают стандарты OGC.

Версии SDK​

Пакеты iOS SDK доступны в двух версиях:

  • Full — полная версия, которая позволяет:
    • Добавлять карту в приложение и управлять ей: добавлять маркеры и геометрические фигуры, управлять движением камеры, отображать слои (например, пробки), работать со стилями карты и т. д.
    • Искать объекты в справочнике: организации, здания, места и другие.
    • Работать с навигатором в приложении в трёх режимах: свободная навигация, ведение по маршруту и симуляция ведения.
    • Строить оптимальные маршруты на карте, в том числе внутри зданий.
    • Использовать офлайн-данные.
  • Map — облегчённая версия, которая позволяет:
    • Добавлять карту в приложение и управлять ей: добавлять маркеры и геометрические фигуры, управлять движением камеры, отображать слои (например, пробки), работать со стилями карты и т. д.
    • Искать объекты в справочнике: организации, здания, места и другие.

Важно

Использовать совместно Full и Map нельзя: это приведёт к ошибке сборки.

Получение ключей доступа​

Для работы с SDK необходимо получить файл ключа dgissdk.key: для подключения к серверам 2ГИС, получения географических данных, а также для использования офлайн-данных и навигатора.

Чтобы получить файл ключа, заполните форму на dev.2gis.ru и укажите ID приложения, для которого будет использоваться ключ. App ID должен соответствовать требованиям.

После получения ключа инициализируйте SDK. Следуйте требованиям:

  • Для одного приложения вы можете инициализировать SDK только один раз. При этом для каждого приложения используется только один ключ. Отдельные ключи требуются в следующих случаях:
    • Если приложение доступно для разных операционных систем.
    • Если у приложения есть несколько вариантов для одной ОС (например, приложение для водителя и приложение для пассажира).
    • Если используются разные версии SDK (Full и Map).
  • App ID должен соответствовать значению app_id в файле с ключом.
  • Изменение файла ключа во время работы приложения не поддерживается. Так как выбор файла ключа происходит при инициализации SDK, вы можете задать им разные названия (по умолчанию используется dgissdk.key): передайте ключ с другим названием через параметр keySource в DGis.Container.

Для работы некоторых функций в SDK используются API поиска и навигации. Доступ к этим API предоставляется вместе с ключом для SDK. Использование API оплачивается дополнительно в зависимости от количества отправленных запросов (и в некоторых случаях — полученных ответов). См. список функциональностей и дополнительных API ниже.

Дополнительные API​

Вы можете просматривать статистику распределения запросов к API в личном кабинете Менеджер Платформы.

Функциональность
Используемые API
Создание поискового движка
(класс SearchManager)		Regions API
Получение результатов поиска
(метод SearchManager.search)		Получение некоторой информации об объектах в доступно только при дополнительной настройке ключа за отдельную плату: см. раздел Структура данных объекта.
Поиск объектов в справочнике по идентификатору
(метод SearchManager.searchById)
Формирование поисковых подсказок
(метод SearchManager.suggest)		Suggest API
Поиск оптимального маршрута с учётом пробок
(класс TrafficRouter)
  • Routing API — все маршруты, кроме общественного транспорта.
  • Public Transport API — маршруты общественного транспорта.
  • Truck Directions API (deprecated) — маршруты для грузовиков. Используется только в старых ключах для SDK, в новых ключах используется Routing API.
Запуск навигатора (метод NavigationManager.start):
  • Routing API — все маршруты, кроме общественного транспорта.
  • Public Transport API — маршруты общественного транспорта.
  • Truck Directions API (deprecated) — маршруты для грузовиков. Используется только в старых ключах для SDK, в новых ключах используется Routing API.
Поиск альтернативных маршрутов
(класс AlternativeRouteSelector)
  • Routing API — все маршруты, кроме общественного транспорта.
  • Public Transport API — маршруты общественного транспорта.
  • Truck Directions API (deprecated) — маршруты для грузовиков. Используется только в старых ключах для SDK, в новых ключах используется Routing API.
Отображение маршрутов на карте
(класс RouteEditorSource)
  • Routing API — все маршруты, кроме общественного транспорта.
  • Public Transport API — маршруты общественного транспорта.
  • Truck Directions API (deprecated) — маршруты для грузовиков. Используется только в старых ключах для SDK, в новых ключах используется Routing API.
Отображение пробок на карте
(класс TrafficSource)		Regions API
Отображение дорожных событий
(класс RoadEventSource)		Regions API

Требования к устройствам​

  • Xcode 14.
  • iOS 16 и выше / iPadOS 16 и выше (это обусловлено использованием SwiftUI в проекте).

Требования к App ID​

App ID может содержать буквы латинского алфавита (A–Z, a–z), цифры (0–9), точки (.) для разделения сегментов и дефисы (-).

Установка​

Swift Package Manager​

Чтобы установить iOS SDK через Swift Package Manager, добавьте в проект пакетную зависимость. См. инструкции по установке Swift-пакетов в документации Apple.

Для подключения SDK укажите URL в зависимости от версии:

  • https://github.com/2gis/mobile-sdk-full-swift-package — для версии SDK Full.
  • https://github.com/2gis/mobile-sdk-map-swift-package — для версии SDK Map.

CocoaPods​

Чтобы установить iOS SDK через CocoaPods, добавьте зависимость DGisMobileSDK.

Используйте версионирование из Swift Package Manager, при этом добавьте постфикс -full или -map в зависимости от необходимой версии SDK.

Спецификацию пода вы можете посмотреть по одному из следующих URL:

  • https://github.com/2gis/mobile-sdk-full-swift-package/blob/master/DGisMobileSDK.podspec — для версии SDK Full.
  • https://github.com/2gis/mobile-sdk-map-swift-package/blob/master/DGisMobileSDK.podspec — для версии SDK Map.

Бинарный артефакт​

Вы можете загрузить фреймворки напрямую, не используя пакетные менеджеры. Для этого обратитесь к репозиторию, содержащему спецификацию пакетов для CocoaPods или Swift Package Manager:

  • https://github.com/2gis/mobile-sdk-full-swift-package — для версии SDK Full.
  • https://github.com/2gis/mobile-sdk-map-swift-package — для версии SDK Map.

В файле Package.swift будет указан URL, ведущий на загрузку архива с SDK по прямой ссылке. Для навигации по версиям используйте теги git.

Демонстрационный проект​

Демонстрационное приложение с исходным кодом см. в GitHub-репозитории.