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

Flutter SDK

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

Примеры использования SDK см. в разделе Примеры.

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

Вы можете использовать Flutter SDK на устройствах с операционными системами iOS, Android и Аврора.

Версии SDK​

Пакеты Flutter SDK доступны в pub.dev в двух версиях:

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

Важно

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

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

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

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

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

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

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

API для работы SDK​

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

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

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

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

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

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

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

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

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

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

Функциональность
API
Поиск оптимального маршрута с учётом пробок
(класс TrafficRouter)
Отображение маршрутов на карте
(класс RouteEditorSource)

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

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

Функциональность
API
Запуск навигатора (метод NavigationManager.start()):
Поиск альтернативных маршрутов
(класс AlternativeRouteSelector)
Отображение дорожных событий
(класс RoadEventSource)		Regions API
Вычисление местоположения устройства по сотовым вышкам и точкам доступа Wi-Fi
(использование RadarApiSettings в Android и ru.dgis.sdk.positioning.RadarSettingsProvider)		Radar API

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

Общие требования​

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

Ключи для ОС Аврора​

Для SDK ключ выписывается для определённого идентификатора приложения. Для ОС Аврора идентификатор приложения формируется по принципу "{QCoreApplication::organizationDomain()}.{QCoreApplication::applicationName()}".

Значение organizationDomain указывается в файле приложения aurora/main.cpp. Например:

int main(int argc, char * argv[])
{
	aurora::Initialize(argc, argv);
	aurora::EnableQtCompatibility();
	// Необходимо указать для успешной проверки ключа
	QCoreApplication::setOrganizationDomain("ru.mobile.sdk.app");
	aurora::RegisterPlugins();
	aurora::Launch();
	return 0;
}

Значение applicationName указывается в конфигурационных файлах приложения. Например:

ApplicationName=flutter_app

и:

Name: ru.dgis.flutter_app

Полные примеры файлов см. в GitHub-репозитории: ru.dgis.flutter_app.desktop и ru.dgis.flutter_app.spec.

Установка​

Для всех платформ​

Чтобы установить Flutter SDK на iOS, Android и Аврора, добавьте в файл pubspec.yaml одну из следующих зависимостей.

  • Для версии SDK Full:

    dependencies:
        flutter:
            sdk: flutter
        flutter_localizations:
            sdk: flutter

        dgis_mobile_sdk_full:
            # При зависимости этого пакета от реального приложения используйте:
            #   dgis_mobile_sdk_full: ^x.y.z
            # См. https://dart.dev/tools/pub/dependencies#version-constraints
            # Приложение в примере связано с плагином, поэтому используется зависимость пути от
            # родительской директории, чтобы использовать текущую версию плагина.
            path: ../
    }

  • Для версии SDK Map:

    dependencies:
        flutter:
            sdk: flutter

        dgis_mobile_sdk_map:
            # При зависимости этого пакета от реального приложения используйте:
            #   dgis_mobile_sdk_map: ^x.y.z
            # См. https://dart.dev/tools/pub/dependencies#version-constraints
            # Приложение в примере связано с плагином, поэтому используется зависимость пути от
            # родительской директории, чтобы использовать текущую версию плагина.
            path: ../

Полные примеры файлов см. в GitHub-репозитории: pubspec.yaml.

Выполните дополнительные шаги установки для Android и ОС Аврора.

Android​

При сборке для Android используется бинарный артефакт в формате .aar. Для правильного подключения добавьте репозиторий с этим артефактом в build.gradle вашего приложения:

repositories {
    maven {
        url "https://artifactory.2gis.dev/sdk-maven-release"
    }
}

Аврора​

Для установки временно доступна только версия SDK Full.

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

  1. Клонируйте репозиторий с SDK для версии Full.

  2. Переключитесь на ветку нужной версии релиза, например версии 12.6.3.

  3. Скопируйте в ваше приложение Flutter реализацию SDK для ОС Аврора.

  4. В файле CMakeLists.txt вашего приложения включите копирование ресурсов, необходимых для корректной работы SDK:

    set(DGIS_DATA_DIR ${CMAKE_CURRENT_LIST_DIR}/../../aurora/data)

    Полный пример файла см. в GitHub-репозитории: CMakeLists.txt.

  5. Чтобы библиотека dgis_c_bindings_linux корректно подключалась к приложению, добавьте в rpm приложения следующую строку:

    %global __requires_exclude ^lib(dgis_c_bindings_linux|dconf|flutter-embedder|maliit-glib|.+_platform_plugin)\\.so.*$

    Полный пример файла см. в GitHub-репозитории: ru.dgis.flutter_app.spec.

  6. Для корректной работы SDK внутри ОС Аврора добавьте следующие разрешения:

    [Desktop Entry]
    Type=Application
    Name=flutter_app
    Comment=A new Flutter project.
    Icon=ru.dgis.flutter_app
    Exec=/usr/bin/ru.dgis.flutter_app
    X-Nemo-Application-Type=silica-qt5

    [X-Application]
    Permissions=Audio;Sensors;SecureStorage;DeviceInfo;Internet;Location;UserDirs
    OrganizationName=ru.dgis
    ApplicationName=flutter_app

    Полный пример файла см. в GitHub-репозитории: ru.dgis.flutter_app.desktop.

  7. Инициализируйте SDK.