iOS SDK
iOS SDK позволяет добавить карту 2ГИС в ваше iOS-приложение. С помощью SDK можно отобразить карту на экране, получать информацию об объектах карты, использовать навигатор, строить маршруты и так далее.
Примеры использования SDK см. в разделе Примеры. Описание всех классов и методов см. в разделе Справочник API.
Картографические данные поддерживают стандарты OGC.
Версии SDK
Пакеты iOS SDK доступны в двух версиях:
- Full — полная версия, которая позволяет:
- Добавлять карту в приложение и управлять ей: добавлять маркеры и геометрические фигуры, управлять движением камеры, отображать слои (например, пробки), работать со стилями карты и т. д.
- Искать объекты в справочнике: организации, здания, места и другие.
- Работать с навигатором в приложении в трёх режимах: свободная навигация, ведение по маршруту и симуляция ведения.
- Строить оптимальные маршруты на карте, в том числе внутри зданий.
- Использовать офлайн-данные.
- Map — облегчённая версия, которая позволяет:
- Добавлять карту в приложение и управлять ей: добавлять маркеры и геометрические фигуры, управлять движением камеры, отображать слои (например, пробки), работать со стилями карты и т. д.
- Искать объекты в справочнике: организации, здания, места и другие.
Важно
Использовать совместно Full и Map нельзя: это приведёт к ошибке сборки.
Получение ключей доступа
Для работы с SDK необходимо получить файл ключа dgissdk.key
: для подключения к серверам 2ГИС, получения географических данных, а также для использования офлайн-данных и навигатора. Чтобы получить файл ключа, заполните форму на dev.2gis.ru и укажите appId
приложения, для которого будет использоваться ключ.
После получения ключа инициализируйте SDK. Следуйте требованиям:
- Для одного приложения вы можете инициализировать SDK только один раз. При этом для каждого приложения используется только один ключ. Отдельные ключи требуются в следующих случаях:
- Если приложение доступно для разных операционных систем.
- Если у приложения есть несколько вариантов для одной ОС (например, приложение для водителя и приложение для пассажира).
- Если используются разные версии SDK (Full и Map).
- Значение
appId
приложения должно соответствовать значению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) |
|
Запуск навигатора (метод NavigationManager.start): |
|
Поиск альтернативных маршрутов (класс AlternativeRouteSelector) |
|
Отображение маршрутов на карте (класс RouteEditorSource) |
|
Отображение пробок на карте (класс TrafficSource) |
Regions API |
Отображение дорожных событий (класс RoadEventSource) |
Regions API |
Требования к устройствам
- Xcode 14.
- iOS 13 и выше / iPadOS 13 и выше (это обусловлено использованием SwiftUI в проекте).
Установка
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-репозитории.