Начало работы

1. Получите ключ доступа

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

Зарегистрируйтесь в личном кабинете Менеджер Платформы.
Купите подписку для доступа к необходимым API. Набор API зависит от необходимых функциональностей и версии SDK. См. подробнее в разделе API для работы SDK.

Использование демо-ключей
Бесплатные демо-ключи недоступны для работы с мобильным SDK.
Создайте ключ доступа или настройте существующий ключ в активной подписке для использования с мобильным SDK.
Скачайте файл ключа dgissdk.key.

Подробнее о работе с ключами и подписками см. в документации личного кабинета.

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

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

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

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

Для 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.

2. Установите SDK

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

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

Для версии Full
Для версии Map

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: ../
}

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:

Клонируйте репозиторий с SDK для версии Full.
Переключитесь на тег нужной версии релиза, например версии 12.6.3.
Скопируйте в ваше приложение Flutter реализацию SDK для ОС Аврора.
В файле CMakeLists.txt вашего приложения включите копирование ресурсов, необходимых для корректной работы SDK:
```
set(DGIS_DATA_DIR ${CMAKE_CURRENT_LIST_DIR}/../../aurora/data)
```
Полный пример файла см. в GitHub-репозитории: CMakeLists.txt.
Чтобы библиотека 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.

Для корректной работы 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.

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

Добавьте полученный файл ключа dgissdk.key в assets приложения.
Вызовите метод initialize() объекта DGis, указав контекст приложения:
```
import 'package:dgis_mobile_sdk_map/dgis.dart' as sdk;

class SomeApp extends StatelessWidget {
    final sdkContext = sdk.DGis.initialize();
}
```
предупреждение
Context может быть создан в единственном экземпляре.

Дополнительно вы можете указать настройки журналирования LogOptions и настройки HTTP-клиента HttpOptions, например таймаут запроса:

import 'package:dgis_mobile_sdk_map/dgis.dart' as sdk;

class SomeApp extends StatelessWidget {

  final sdkContext = sdk.DGis.initialize(
    logOptions: const sdk.LogOptions(
      customLevel: sdk.LogLevel.verbose,
      systemLevel: sdk.LogLevel.verbose,
    ),
    httpOptions: const sdk.HttpOptions(
      timeout: Duration(seconds: 5),
    ),
  );
}

Дополнительные настройки

Vendor Config

Для переопределения некоторых настроек работы SDK используется файл в формате VendorConfig, который передается при инициализации SDK.

Существует несколько способов создать экземпляр класса VendorConfig:

VendorConfigFromAsset — файл необходимо расположить в каталоге assets исходного кода приложения и указать имя файла в конструкторе.
VendorConfigFromFile — файл необходимо расположить в файловой системе устройства и указать абсолютный путь до него.
VendorConfigFromString — в конструктор необходимо передать строку с содержимым файла формата JSON.

Созданный экземпляр VendorConfig передается в метод DGis.initialize() параметром vendorConfig.

Работа с офлайн-данными

Мобильный SDK (версия Full) позволяет работать с данными карты, справочника и навигатора офлайн из предварительно загруженных пакетов. Это может быть полезно в условиях плохой связи или при её полном отсутствии.

Чтобы настроить работу в режиме офлайн:

Обратитесь в отдел продаж 2ГИС, чтобы получить права на работу с офлайн-данными. Вы можете запросить права на офлайн-данные всех компонентов (карта, справочник, построение маршрутов) или выбрать только необходимые.
Скачайте файлы с данными для территорий, где необходима офлайн-работа приложения, через TerritoryManager.
Настройте компоненты SDK для работы с предзагруженными данными:
- Карта: создайте источник данных и укажите нужный режим работы.
- Справочник: используйте нужный метод для создания справочника объектов.
- Построение маршрутов: по умолчанию настроен гибридный режим. Подробнее см. документацию о маршрутах.

Язык приложения

Чтобы установить язык приложения, передайте список локалей (Locale) в методе overrideLocales() класса LocaleManager.

Язык навигатора

В зависимости от выбранной локали меняется язык звуковых оповещений в навигаторе.

Пример установки англоязычной локали:

import 'package:dgis_mobile_sdk_map/dgis.dart' as sdk;

// Создание объекта Locale с указанием языка и региона
final locale = sdk.Locale(language: sdk.Language("en"), region: sdk.Region("EN"));

// Установка локали для приложения
sdk.getLocaleManager(sdkContext).overrideLocales([locale]);

Доступные значения параметров language и region:

`language`	`region`
`ru` (русский)	`RU` (Россия)
`en` (английский)	`RU` (Россия), `AE` (ОАЭ), `AM` (Армения)
`ar` (арабский)	`AE` (ОАЭ)
`az` (азербайджанский)	`AZ` (Азербайджан)
`hy` (армянский)	`AM` (Армения)
`kk` (казахский)	`KZ` (Казахстан)
`ky` (кыргызский)	`KG` (Кыргызстан)
`uz` (узбекский)	`UZ` (Узбекистан)
`ka` (грузинский)	`GE` (Грузия)
`tg` (таджикский)	`TJ` (Таджикистан)

Полный список доступных комбинаций языков и регионов см. в описании параметра locale в документации Places API.

1. Получите ключ доступа​

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

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

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

2. Установите SDK​

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

Android​

Аврора​

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

Дополнительные настройки​

Vendor Config​

Работа с офлайн-данными​

Язык приложения​