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​

Common 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.

Keys for Aurora OS​

For the SDK, the key is issued for a specific application identifier. For Aurora OS, the application identifier is formed as "{QCoreApplication::organizationDomain()}.{QCoreApplication::applicationName()}".

The organizationDomain value is specified in the application file aurora/main.cpp. For example:

int main(int argc, char * argv[])
{
	aurora::Initialize(argc, argv);
	aurora::EnableQtCompatibility();
	// Required for successful key verification
	QCoreApplication::setOrganizationDomain("ru.mobile.sdk.app");
	aurora::RegisterPlugins();
	aurora::Launch();
	return 0;
}

The applicationName value is specified in the application configuration files. For example:

ApplicationName=flutter_app

and:

Name: ru.dgis.flutter_app

Full examples of the files can be found in the GitHub repository: ru.dgis.flutter_app.desktop and ru.dgis.flutter_app.spec.

2. Install SDK​

For all platforms​

To install the Flutter SDK on iOS, Android, or Aurora OS, add one of the following dependencies to your pubspec.yaml file:

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

    dgis_mobile_sdk_full:
        # When depending on this package from a real application you should use:
        #   dgis_mobile_sdk_full: ^x.y.z
        # See https://dart.dev/tools/pub/dependencies#version-constraints
        # The example application is bundled with the plugin so we use a path dependency on
        # the parent directory to use the current plugin's version.
        path: ../
}

For full file examples, see the GitHub repository: pubspec.yaml.

Follow additional installation steps for Android and Aurora OS.

Android​

A binary artifact in the .aar format is used when building for Android. To connect correctly, add a repository with this artifact to build.gradle of your application:

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

Aurora OS​

Version availability

For installing the SDK for Aurora OS, only the Full version is temporarily available.

To install the Flutter SDK:

  1. Clone the repository with the Full SDK version.

  2. Switch to the tag of the desired release version, for example version 12.6.3.

  3. Copy the Aurora OS SDK implementation into your Flutter application.

  4. In your application CMakeLists.txt file, include the copying of resources required for the SDK to function correctly:

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

    See a full example of the file in the GitHub repository: CMakeLists.txt.

  5. To ensure the dgis_c_bindings_linux library is correctly linked to the application, add the following line to the application rpm file:

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

    See a full example of the file in the GitHub repository: ru.dgis.flutter_app.spec.

  6. To ensure the SDK functions correctly within Aurora OS, add the following permissions:

    [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

    See a full example of the file in the GitHub repository: ru.dgis.flutter_app.desktop.

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:

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

    class SomeApp extends StatelessWidget {
        final sdkContext = sdk.DGis.initialize();
    }
    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 a request timeout:

    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),
        ),
      );
    }

Additional settings​

Vendor Config​

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

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

  • VendorConfigFromAsset - locate the file in the assets directory of the application source code and specify the file name in the constructor.
  • VendorConfigFromFile - locate the file on the device file system and specify the absolute path to it.
  • VendorConfigFromString - pass a string with the contents of the JSON file 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.

  1. 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:

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

// Creating a Locale object with the specified language and region
final locale = sdk.Locale(language: sdk.Language("en"), region: sdk.Region("EN"));

// Setting the locale for the application
sdk.getLocaleManager(sdkContext).overrideLocales([locale]);

Available language values (parameters language and region respectively):

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