Android SDK

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

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

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

Версии SDK

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

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

Важно

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

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

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

1. Чтобы получить файл ключа dgissdk.key, заполните форму на dev.2gis.ru и укажите:

   • ID приложения (App ID), для которого будет использоваться ключ. Убедитесь, что App ID соответствует требованиям.
   • Список API, к которым требуется доступ. Зависит от необходимых функциональностей и версии SDK. См. подробнее в разделе API для работы SDK.

2. Убедитесь, что выполнены требования к ключу.

После получения ключа инициализируйте SDK.

API для работы SDK

В зависимости от нужных функциональностей, для работы SDK требуются ключи доступа к API карт, поиска и навигации. Доступные возможности зависят от версии SDK: Full или Map.

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

Карта (для Full и Map)

Подробнее о доступных возможностях см. в инструкции Карта.

Функциональность	API
Создание карты в приложении (класс MapView)	Tiles API Regions API
Отображение пробок на карте (класс TrafficSource)	Regions API

Справочник (для Full и Map)

Подробнее о доступных возможностях см. в инструкции Справочник.

Функциональность	API
Создание поискового движка (класс SearchManager)	Regions API
Получение результатов поиска (метод SearchManager.search())	Places API Markers API Получение некоторой информации об объектах в доступно только при дополнительной настройке ключа за отдельную плату: см. раздел Структура данных объекта.
Поиск объектов в справочнике по идентификатору (метод SearchManager.searchById())	Places API Markers API
Формирование поисковых подсказок (метод SearchManager.suggest())	Suggest API

Маршруты (только для Full)

Подробнее о доступных возможностях см. в инструкции Маршруты.

Функциональность	API
Поиск оптимального маршрута с учётом пробок (класс TrafficRouter)	Directions API — все маршруты, кроме общественного транспорта. Public Transport API — маршруты общественного транспорта. Truck Directions API — маршруты для грузовиков.
Отображение маршрутов на карте (класс RouteEditorSource)	Directions API — все маршруты, кроме общественного транспорта. Public Transport API — маршруты общественного транспорта. Truck Directions API — маршруты для грузовиков.

Навигация (только для Full)

Подробнее о доступных возможностях см. в инструкции Навигация.

Функциональность	API
Запуск навигатора (метод NavigationManager.start()): в режиме свободной навигации, в режиме ведения по маршруту.	Directions API — все маршруты, кроме общественного транспорта. Public Transport API — маршруты общественного транспорта. Truck Directions API — маршруты для грузовиков.
Поиск альтернативных маршрутов (класс AlternativeRouteSelector)	Directions API — все маршруты, кроме общественного транспорта. Public Transport API — маршруты общественного транспорта. Truck Directions API — маршруты для грузовиков.
Отображение дорожных событий (класс RoadEventSource)	Regions API
Вычисление местоположения устройства по сотовым вышкам и точкам доступа Wi-Fi (использование RadarApiSettings в DefaultLocationSource)	Radar API

Требования

Требования к ключам

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

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

• Можно использовать буквы латинского алфавита (A–Z, a–z), цифры (0–9), точки (.) для разделения сегментов и дефисы (-).
• App ID должен содержать минимум два сегмента, разделённых точками (например, com.example.app). Каждый сегмент должен начинаться с буквы.

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

• Android 6.0 (Marshmallow) и выше.
• Поддерживаемые архитектуры: x86_64, x86, armeabi-v7a, arm64-v8a.
• OpenGL ES 3.1.

Установка

Чтобы установить Android SDK:

1. Укажите пользовательский репозиторий в вашем файле settings.gradle.kts:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
           maven {
               url = URI("https://artifactory.2gis.dev/sdk-maven-release")
           }
       }
   }

2. Добавьте одну из следующих зависимостей.

   • Для версии 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, содержащий только необходимые библиотеки для конкретного устройства:

1. Соберите app bundle, выбрав этот вариант сборки в Gradle.
2. Получите APK по необходимым критериям (например, только для arm64-v8a) из app bundle с помощью bundletool.

Полученный APK будет отражать реальный размер, который получит пользователь при загрузке приложения из Google Play.