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 a dgissdk.key access key file:

  1. Sign in to the Platform Manager.

  2. Create an access key for the required APIs in one of the following ways:

    • Create a free demo key. The demo key is created once, provides access to all current 2GIS APIs, and is valid for one month from the date of creation. For each service, a limit on the number of requests applies: see the Limits section.

      Later, when you purchase a subscription, you can switch the demo key to production mode without creating a new key. See the Changing key mode instructions.

    • 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. See current prices and limits in the Pricing and limits section.

      The first key in the subscription is created automatically. Make sure it is configured for use with the mobile SDK: see the instructions.

  3. Download the dgissdk.key file.

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.

Available values for the language and region parameters:

languageregion
ru (Russian)RU (Russia)
en (English)RU (Russia), AE (United Arab Emirates), AM (Armenia)
ar (Arabic)AE (United Arab Emirates)
az (Azerbaijani)AZ (Azerbaijan)
hy (Armenian)AM (Armenia)
kk (Kazakh)KZ (Kazakhstan)
ky (Kyrgyz)KG (Kyrgyzstan)
uz (Uzbek)UZ (Uzbekistan)
ka (Georgian)GE (Georgia)
tg (Tajik)TJ (Tajikistan)

For the full list of available language and region combinations, see the locale parameter description in the Places API documentation.