Skip to main content

Getting started

1. Get an access key​

To connect to 2GIS servers, obtain geodata, and enable SDK features, you need to get an access key file:

  1. Sign in to the Platform Manager.
  2. Purchase a subscription for required APIs. The list depends on the required features and the SDK version. For more details, see the API for SDK operation section.
  3. Create an access key or configure an existing key for use with the mobile SDK.
  4. Download the dgissdk.key file.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.

Key usage requirements​

  • For SDK version 13.3.0 and later, specifying an App ID when creating a key is optional. Specify an App ID only if you are using earlier SDK versions or plan to work with offline data.
  • If an App ID is specified in the key, you can use this key only for one application. Separate keys are required in the following cases:
    • If the application is available for different operating systems.
    • If the application has several alternatives for a single OS (for example, one application for the driver and another for the passenger).
    • If different SDK versions are used (Full and Map).
  • Changing the key file while the application is running is not supported.

2. Install SDK​

  1. Declare a custom repository in your settings.gradle.kts file:

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

  2. Add a dependency:

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

3. Initialize SDK​

  1. Add the received key file dgissdk.key to assets of the application.

  2. Call the initialize() method of a DGis object and specify the application context:

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

        override fun onCreate() {
            super.onCreate()

            sdkContext = DGis.initialize(
                this
            )
        }
    }
    warning

    Context can be created in a single instance only.

  3. Additionally, you can specify logging settings (LogOptions) and HTTP client settings (HttpOptions) such as caching. Using LogOptions, you can also configure sending logs to Firebase Crashlytics.

    // Logging settings
    val logOptions = LogOptions(
        LogLevel.VERBOSE
    )

    // HTTP client settings
    val httpOptions = HttpOptions(
        useCache = false
    )

    // Consent to personal data processing
    val dataCollectConsent = PersonalDataCollectionConsent.GRANTED

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

Additional settings​

Sending logs to Firebase Crashlytics​

Object of the LogOptions class allows you not only to configure the logging level but also to specify a custom log sink using the customSink parameter. LogSink is an interface with a single write() method that must be implemented.

Implementation of sending logs to Firebase Crashlytics can look as follows:

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

Pass an instance of this class to the initialize() method of the DGis object:

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

Vendor Config​

To override some SDK operation settings, a file in the format VendorConfig is used, which is passed during SDK initialization.

There are several ways to create an instance of the VendorConfig class:

  • VendorConfigFromAsset - the file should be located in the assets directory of the application source code, and you must specify the file name in the constructor.
  • VendorConfigFromFile - the file should be located on the device file system and you must specify the absolute path to it.
  • VendorConfigFromString - a string with the contents of the json file should be passed to the constructor.

The created VendorConfig instance is passed to the DGis.initialize() method with the vendorConfig parameter.

Working with offline data​

Mobile SDK (the Full version) allows you to work with map, directory, and routing data offline from preloaded packages. This can be helpful when the network connection is low or missing.

To configure the offline mode:

  1. Contact 2GIS support to get access rights for working with offline data. You can request access to offline data for all components (map, directory, routing) or select only the required ones.

  2. Use TerritoryManager to download data files for territories where your application must work offline.

    See a code example of loading territories.

  3. Configure SDK components for working with preloaded data:

Application language​

To set the application language, pass a list of locales (Locale) to the overrideLocales() method of the LocaleManager class.

Navigator language

Depending on the selected locale, the language of sound notifications in the navigator changes.

Example of setting the English locale:

// Creating a Locale object with the specified language and region
val locale = Locale(language = "en", region = "EN")

/// Setting the locale for the application
LocaleManager.instance(sdkContext).overrideLocales(listOf(locale))

Available language values (parameters language and region respectively):

  • ru-RU - Russian
  • en-EN - English
  • ar-AE - Arabic