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

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).
Изменение файла ключа во время работы приложения не поддерживается.

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

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

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

Добавьте зависимость:

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

dependencies {
    implementation 'ru.dgis.sdk:sdk-full:latest.release'
}

dependencies {
    implementation 'ru.dgis.sdk:sdk-map:latest.release'
}

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

Добавьте полученный файл ключа dgissdk.key в assets приложения.

Вызовите метод initialize() объекта DGis, указав контекст приложения:

class Application : Application() {
    lateinit var sdkContext: Context

    override fun onCreate() {
        super.onCreate()

        sdkContext = DGis.initialize(
            this
        )
    }
}

предупреждение

Context может быть создан в единственном экземпляре.

Дополнительно вы можете указать настройки журналирования (LogOptions) и настройки HTTP-клиента (HttpOptions), такие как кеширование. С помощью LogOptions также можно настроить отправку логов в Firebase Crashlytics.

// Настройки журналирования
val logOptions = LogOptions(
    LogLevel.VERBOSE
)

// Настройки HTTP-клиента
val httpOptions = HttpOptions(
    useCache = false
)

// Согласие на сбор и отправку персональных данных
val dataCollectConsent = PersonalDataCollectionConsent.GRANTED

sdkContext = DGis.initialize(
    appContext = this,
    dataCollectConsent = dataCollectConsent,
    logOptions = logOptions,
    httpOptions = httpOptions
)

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

Отправка логов в Firebase Crashlytics

Объект класса LogOptions, кроме настройки уровня логирования, также позволяет использовать собственный приёмник логов с помощью параметра customSink. LogSink – интерфейс с единственным методом write(), который необходимо реализовать.

Реализация для отправки сообщений лога в Firebase Crashlytics может выглядеть так:

class FirebaseLogSink : LogSink {
    override fun write(message: LogMessage) {
        FirebaseCrashlytics.getInstance().log(message.text)
    }
}

Передайте экземпляр этого класса в метод initialize() объекта DGis:

sdkContext = DGis.initialize(
            ...
            logOptions = LogOptions(
                ...
                customSink = FirebaseLogSink()
            )
            ...
        )

Vendor Config

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

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

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

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

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

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

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

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

См. пример кода для загрузки территорий.
Настройте компоненты SDK для работы с предзагруженными данными:
- Карта: создайте источник данных и укажите нужный режим работы.
- Справочник: используйте нужный метод для создания справочника объектов.
- Построение маршрутов: по умолчанию настроен гибридный режим. Подробнее см. документацию о маршрутах.

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

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

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

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

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

Для версии SDK 13.0.0 и выше
Для версии SDK 12.x

// Создание объекта Locale с указанием языка и региона
val locale = Locale(language = "en", region = "EN")

// Установка локали для приложения
LocaleManager.instance(sdkContext).overrideLocales(listOf(locale))

// Создание объекта Locale с указанием языка и региона
val locale = Locale(language = "en", region = "EN")

// Установка локали для приложения
getLocaleManager(sdkContext).overrideLocales(listOf(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​

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

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

Отправка логов в Firebase Crashlytics​

Vendor Config​

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

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