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)	Places API Markers API Получение некоторой информации об объектах в доступно только при дополнительной настройке ключа за отдельную плату: см. раздел Структура данных объекта.
Поиск объектов в справочнике по идентификатору (метод SearchManager.searchById)	Places API Markers API
Формирование поисковых подсказок (метод 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
Вычисление местоположения устройства по сотовым вышкам и точкам доступа 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.