Начало работы
1. Получите ключ доступа
Чтобы подключиться к серверам 2ГИС, получать геоданные и включить возможности SDK, получите файл ключа доступа dgissdk.key:
-
Зарегистрируйтесь в личном кабинете Менеджер Платформы.
-
Создайте ключ для доступа к необходимым API одним из способов:
-
Создайте бесплатный демо-ключ. Демо-ключ создаётся один раз, предоставляет доступ ко всем актуальным API 2ГИС и действует один месяц со дня создания. Для каждого сервиса действует лимит на количество запросов: см. раздел Лимиты.
В дальнейшем при покупке подписки вы сможете перевести демо-ключ в «боевой» режим без необходимости создавать новый ключ. См. инструкцию Изменение режима ключа.
-
Купите подписку для доступа к необходимым API. Набор API зависит от необходимых функциональностей и версии SDK, подробнее см. в разделе API для работы SDK. Актуальную стоимость и лимиты см. в инструкции Тарифы и лимиты.
Первый ключ в подписке создаётся автоматически. Убедитесь, что он настроен для использования с мобильным SDK: см. инструкцию.
-
-
Скачайте файл ключа
dgissdk.key.
Требования к работе с ключами
- Указание App ID при создании ключа необязательно. Укажите App ID, только если вы планируете работать с офлайн-данными.
- Если в ключе указан App ID, вы можете использовать этот ключ только для одного приложения. Отдельные ключи требуются в следующих случаях:
- Если приложение доступно для разных операционных систем.
- Если у приложения есть несколько вариантов для одной ОС (например, приложение для водителя и приложение для пассажира).
- Если используются разные версии SDK (Full и Map).
- Изменение файла ключа во время работы приложения не поддерживается.
2. Установите SDK
Для всех платформ
Чтобы установить React Native SDK на iOS и Android, добавьте в проект один из пакетов:
- Для версии Map
- Для версии Full
npm install @2gis/dgis-mobile-sdk-map react-native-safe-area-context
или:
yarn add @2gis/dgis-mobile-sdk-map react-native-safe-area-context
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.
-
Добавьте репозиторий с этим артефактом в Gradle-конфигурацию проекта:
repositories {google()mavenCentral()maven {url "https://artifactory.2gis.dev/sdk-maven-release"}} -
Поместите файл ключа в
assetsприложения:android/app/src/main/assets/dgissdk.key
iOS
-
Добавьте
dgissdk.keyв app target Xcode-проекта как ресурс приложения: файл должен оказаться вBundle.main. -
После установки пакета обновите CocoaPods-зависимости:
cd iospod 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 использует локали операционной системы.
Доступные значения параметров language и region:
language | region |
|---|---|
ru (русский) | RU (Россия) |
en (английский) | RU (Россия), AE (ОАЭ), AM (Армения) |
ar (арабский) | AE (ОАЭ) |
az (азербайджанский) | AZ (Азербайджан) |
hy (армянский) | AM (Армения) |
kk (казахский) | KZ (Казахстан) |
ky (кыргызский) | KG (Кыргызстан) |
uz (узбекский) | UZ (Узбекистан) |
ka (грузинский) | GE (Грузия) |
tg (таджикский) | TJ (Таджикистан) |
Полный список доступных комбинаций языков и регионов см. в описании параметра locale в документации Places API.