Skip to main content

Getting started

1. Get an access key​

To connect to 2GIS servers, obtain geodata, and enable SDK features, get the dgissdk.key access key file:

  1. Sign in to the Platform Manager.

  2. Purchase a subscription to access the required APIs. The set of APIs depends on the required features and the SDK version. For more information, see the API for SDK operation section.

Using demo keys

Free demo keys are not available for use with the mobile SDK.

  1. Create an access key or configure an existing key in an active subscription for use with the mobile SDK.
  2. Download the dgissdk.key key file.

For more information on working with keys and subscriptions, see the Platform Manager documentation.

Key usage requirements​

  • Specifying an App ID when creating a key is optional. Specify an App ID only if you 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 variants for one OS (for example, an application for drivers and an application for passengers).
    • If different SDK versions are used (Full and Map).
  • Changing the key file while the application is running is not supported.

2. Install SDK​

For all platforms​

To install React Native SDK on iOS and Android, add one of the following packages to your project:

npm install @2gis/dgis-mobile-sdk-full react-native-safe-area-context react-native-svg

or:

yarn add @2gis/dgis-mobile-sdk-full react-native-safe-area-context react-native-svg

After installation, complete the additional steps for Android and iOS.

Android​

A binary artifact in the .aar format is used when building for Android.

  1. Add the repository containing this artifact to the Gradle configuration of your project:

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

  2. Place the key file in the application assets:

    android/app/src/main/assets/dgissdk.key

iOS​

  1. Add dgissdk.key to the app target of the Xcode project as an application resource. The file must be included in Bundle.main.

  2. After installing the package, update the CocoaPods dependencies:

    cd ios
    pod install

3. Initialize SDK​

Create a Context once for the lifetime of the application or screen where the SDK is used. By default, the SDK looks for the key in the dgissdk.key asset.

import React, { createContext, useContext, useEffect, useRef } from 'react';
import { DGis, type Context } from '@2gis/dgis-mobile-sdk-full';

const SdkContext = createContext<Context | null>(null);

export function SdkProvider({ children }: { children: React.ReactNode }) {
  const contextRef = useRef<Context | null>(null);

  if (contextRef.current === null) {
    contextRef.current = DGis.createContext();
  }

  useEffect(() => {
    return () => {
      if (contextRef.current !== null) {
        DGis.releaseContext(contextRef.current);
        contextRef.current = null;
      }
    };
  }, []);

  return (
    <SdkContext.Provider value={contextRef.current}>
      {children}
    </SdkContext.Provider>
  );
}

export function useSdkContext(): Context {
  const context = useContext(SdkContext);
  if (context === null) {
    throw new Error('SdkProvider is not mounted');
  }
  return context;
}

To specify the key source explicitly, pass it to DGis.createContext():

import {
  DGis,
  HttpOptions,
  KeyFromAsset,
  KeySource,
  LogLevel,
  LogOptions,
  PersonalDataCollectionConsent,
  VendorConfig,
} from '@2gis/dgis-mobile-sdk-full';

const context = DGis.createContext(
  new HttpOptions({}),
  new LogOptions({
    systemLevel: LogLevel.Warning,
    customLevel: LogLevel.Warning,
  }),
  VendorConfig.none(),
  KeySource.fromAsset(new KeyFromAsset({ path: 'dgissdk.key' })),
  PersonalDataCollectionConsent.Granted,
);

Additional settings​

Vendor Config​

To override the SDK configuration, pass VendorConfig when creating the context. For Android, specify the path relative to the assets directory. For iOS, specify the path relative to Bundle.main.

import {
  DGis,
  HttpOptions,
  KeyFromAsset,
  KeySource,
  LogOptions,
  VendorConfig,
  VendorConfigFromAsset,
} from '@2gis/dgis-mobile-sdk-full';

const context = DGis.createContext(
  new HttpOptions({}),
  new LogOptions({}),
  VendorConfig.fromAsset(new VendorConfigFromAsset({ path: 'vendorConfig.json' })),
  KeySource.fromAsset(new KeyFromAsset({ path: 'dgissdk.key' })),
);

Working with offline data​

Mobile SDK (Full version) allows you to work offline with map, directory, and navigator data from preloaded packages. This can be useful when the network connection is poor or unavailable.

To configure offline mode:

  1. Contact the 2GIS sales department to obtain permission to work with offline data. You can request access to offline data for all components (map, directory, and routing) or select only the required components.

  2. Create a DgisSource in offline or hybrid mode and add it when creating the map or using map.addSource().

    import {
      DgisSource,
      DgisSourceWorkingMode,
      MapControllerOptions,
    } from '@2gis/dgis-mobile-sdk-full';

    const source = DgisSource.createDgisSource(
      context,
      DgisSourceWorkingMode.HybridOnlineFirst,
    );

    const options = new MapControllerOptions({
      sources: [source],
    });

  3. Use TerritoryManager to download data files for the territories where the application must work offline. Start the installation using the territory object.

    import { TerritoryManager } from '@2gis/dgis-mobile-sdk-full';

    const territoryManager = TerritoryManager.instance(context);
    const connection = territoryManager.territoriesChannel.subscribe(territories => {
      const city = territories.find(item => item.infoChannel.value.name === 'Novosibirsk');
      city?.install();
    });

    // When the subscription is no longer needed:
    connection.disconnect();

Application language​

To override the SDK locale, use LocaleManager.

import { Locale, LocaleManager } from '@2gis/dgis-mobile-sdk-full';

const localeManager = LocaleManager.instance(context);

localeManager.overrideLocales([
  new Locale({ language: 'ru', region: 'RU' }),
]);

If the locale is not set explicitly, the SDK uses the operating system locales.