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

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

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

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

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

Работать с ключами можно в Менеджере Платформы: подробнее см. в документации личного кабинета.

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

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

2. Установка 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. Добавьте зависимость:

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

3. Инициализация SDK​

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

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

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

        override fun onCreate() {
            super.onCreate()

            sdkContext = DGis.initialize(
                this
            )
        }
    }
    предупреждение

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

  3. Дополнительно вы можете указать настройки журналирования (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) позволяет работать с данными карты, справочника и навигатора офлайн из предзагруженных пакетов. Это может быть полезно в условиях плохой связи или при её полном отсутствии.

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

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

  2. Скачайте файлы с данными для территорий, где необходима офлайн-работа приложения, через TerritoryManager.

    См. пример кода для загрузки территорий.

  3. Настройте компоненты SDK для работы с предзагруженными данными:

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

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

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

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

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

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

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

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

  • ru-RU — русский;
  • en-EN — английский;
  • ar-AE — арабский.