Android SDK
Android SDK позволяет добавить карту 2ГИС в ваше Android-приложение. С помощью SDK можно отобразить карту на экране, получать информацию об объектах карты, использовать навигатор, строить маршруты и так далее.
Примеры использования SDK см. в разделе Примеры. Описание всех классов и методов см. в разделе Справочник API.
Картографические данные поддерживают стандарты OGC.
Версии SDK
Пакеты Android SDK доступны в двух версиях:
- Full — полная версия, которая позволяет:
- Добавлять карту в приложение и управлять ей: добавлять маркеры и геометрические фигуры, управлять движением камеры, отображать слои (например, пробки), работать со стилями карты и т. д.
- Искать объекты в справочнике: организации, здания, места и другие.
- Работать с навигатором в приложении в трёх режимах: свободная навигация, ведение по маршруту и симуляция ведения.
- Строить оптимальные маршруты на карте, в том числе внутри зданий.
- Использовать офлайн-данные.
- Map — облегчённая версия, которая позволяет:
- Добавлять карту в приложение и управлять ей: добавлять маркеры и геометрические фигуры, управлять движением камеры, отображать слои (например, пробки), работать со стилями карты и т. д.
- Искать объекты в справочнике: организации, здания, места и другие.
Важно
Использовать совместно Full и Map нельзя: это приведёт к ошибке сборки.
Получение ключей доступа
Для работы с SDK необходимо получить файл ключа dgissdk.key
: для подключения к серверам 2ГИС, получения географических данных, а также для использования офлайн-данных и навигатора. Чтобы получить файл ключа, заполните форму на dev.2gis.ru и укажите appId
приложения, для которого будет использоваться ключ.
После получения ключа инициализируйте SDK. Следуйте требованиям:
- Для одного приложения вы можете инициализировать SDK только один раз. При этом для каждого приложения используется только один ключ. Отдельные ключи требуются в следующих случаях:
- Если приложение доступно для разных операционных систем.
- Если у приложения есть несколько вариантов для одной ОС (например, приложение для водителя и приложение для пассажира).
- Если используются разные версии SDK (Full и Map).
- Значение
appId
приложения должно соответствовать значениюapp_id
в файле с ключом. - Изменение файла ключа во время работы приложения не поддерживается.
Для работы некоторых функций в 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 |
Вычисление местоположения устройства по сотовым вышкам и точкам доступа Wi-Fi (использование RadarApiSettings в DefaultLocationSource) |
Radar API |
Требования к устройствам
- Android 5.0 (Lollipop) и выше.
- Поддерживаемые архитектуры: x86_64, x86, armeabi-v7a, arm64-v8a.
- OpenGL ES 3.1.
Установка
Чтобы установить Android SDK:
-
Укажите пользовательский репозиторий в вашем файле
build.gradle
:repositories { maven { url "https://artifactory.2gis.dev/sdk-maven-release" } }
-
Добавьте одну из следующих зависимостей.
-
Для версии SDK Full:
dependencies { implementation 'ru.dgis.sdk:sdk-full:latest.release' }
-
Для версии SDK Map:
dependencies { implementation 'ru.dgis.sdk:sdk-map:latest.release' }
-
Демонстрационный проект
Демонстрационное приложение с исходным кодом см. в GitHub-репозитории.
Размер приложения
Размер вашего приложения может заметно увеличиться после добавления SDK в проект. См. ниже описание причины и возможные стратегии для борьбы с этим увеличением.
Процессорные архитектуры
Современные устройства Android могут иметь различные типы процессоров: x86-64, x86, ARMv7 и ARMv8. Для кода, написанного на Java или Kotlin, это не является проблемой, так как он исполняется в виртуальной машине и абстрагируется от конкретного железа. Однако, для нативного кода тип процессора играет важную роль.
Наша библиотека содержит четыре версии для всех типов ABI (Application Binary Interface), чтобы обеспечить поддержку всех этих типов процессоров.
Оптимизация размера
Чтобы сократить размер приложения, вы можете использовать разделение APK по типам ABI. Это позволит собирать и загружать только необходимые библиотеки для конкретного устройства пользователя. См. инструкции по сборке и загрузке в документации Android. Если вы используете Android App Bundle, Google Play может автоматически пересобирать приложение под нужные типы процессоров для конкретных устройств пользователей.
Проверка размера
Чтобы увидеть фактический размер APK, который будет загружаться пользователем, рекомендуется использовать инструмент bundletool. Это поможет получить APK, содержащий только необходимые библиотеки для конкретного устройства:
- Соберите app bundle, выбрав этот вариант сборки в Gradle.
- Получите APK по необходимым критериям (например, только для arm64-v8a) из app bundle с помощью bundletool.
Полученный APK будет отражать реальный размер, который получит пользователь при загрузке приложения из Google Play.