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

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

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

1. Зарегистрируйтесь в личном кабинете Менеджер Платформы.

2. Купите подписку для доступа к необходимым API. Набор API зависит от необходимых функциональностей и версии SDK. См. подробнее в разделе API для работы SDK.

   Использование демо-ключей

   Бесплатные демо-ключи недоступны для работы с мобильным SDK.

3. Создайте ключ доступа или настройте существующий ключ в активной подписке для использования с мобильным SDK.

4. Скачайте файл ключа dgissdk.key.

Подробнее о работе с ключами и подписками см. в документации личного кабинета.

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

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

2. Установите SDK

Для всех платформ

Чтобы установить React Native SDK на iOS и Android, добавьте в проект один из пакетов:

Для версии Map

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

или:

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

Для версии Full

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

или:

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

После установки выполните дополнительные шаги для Android и iOS.

Android

При сборке для Android используется бинарный артефакт в формате .aar.

1. Добавьте репозиторий с этим артефактом в Gradle-конфигурацию проекта:

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

2. Поместите файл ключа в assets приложения:

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

iOS

1. Добавьте dgissdk.key в app target Xcode-проекта как ресурс приложения: файл должен оказаться в Bundle.main.

2. После установки пакета обновите CocoaPods-зависимости:

   cd ios
   pod install

3. Инициализируйте SDK

Создайте Context один раз на время жизни приложения или экрана, где используется SDK. По умолчанию SDK ищет ключ в asset-е dgissdk.key.

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

Если нужно указать источник ключа явно, передайте его в 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,
);

Дополнительные настройки

Vendor Config

Чтобы переопределить конфигурацию SDK, передайте VendorConfig при создании контекста. Для Android путь указывается относительно директории assets, для iOS — относительно 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' })),
);

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

Чтобы переопределить локаль SDK, используйте LocaleManager.

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

const localeManager = LocaleManager.instance(context);

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

Если локаль не задана явно, SDK использует локали операционной системы.