@2gis/dgis-mobile-sdk-map

2GIS Mobile SDK (map flavor) for React Native.

Requires React Native 0.74+ with the New Architecture enabled, React 18+.

Installation

npm install @2gis/dgis-mobile-sdk-map

This package has a peer dependency on react-native-safe-area-context (^5.5.2) — install it if your app doesn't already have it.

SDK key (dgissdk.key)

The SDK authenticates with a key file named dgissdk.key, obtained from 2GIS. It is read by name from the app bundle, so it must be added to each platform:

• Android: android/app/src/main/assets/dgissdk.key
• iOS: add dgissdk.key to the app target's Copy Bundle Resources

The key is bound to an application identifier. Your Android applicationId and iOS bundle identifier must match the id the key was issued for, otherwise SDK initialization fails with a "key does not match the application" error.

Android setup

1. Add the 2GIS Maven repository (for the native artifact) in android/build.gradle:

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

2. minSdk 24+ and the New Architecture enabled (default on RN 0.76+).

3. Initialize the SDK in MainApplication.kt, in onCreate(), before any map is used:

   import ru.dgis.sdk.platform.LogLevel
   import ru.dgis.sdk.platform.LogOptions
   import ru.dgis.sdk.reactnative.DgisMobileSdkModule
   import ru.dgis.sdk.reactnative.GraphicsApi
   
   override fun onCreate() {
     super.onCreate()
     loadReactNative(this)
     DgisMobileSdkModule.init(
       application = this,
       graphicsApi = GraphicsApi.OPEN_GL,
       vulkanEmulatorSupportEnabled = true,
       logOptions = LogOptions(LogLevel.INFO, LogLevel.INFO, null),
     )
   }

4. Permissions in AndroidManifest.xml:

   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

iOS setup

1. Deployment target iOS 16.0 — set platform :ios, '16.0' in the Podfile and the app target's deployment target to 16.0.

2. In the Podfile post_install, apply these build settings to all pods:

   installer.pods_project.targets.each do |target|
     target.build_configurations.each do |config|
       config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '16.0'
       config.build_settings['CLANG_ENABLE_EXPLICIT_MODULES'] = 'NO'
       config.build_settings['SWIFT_ENABLE_EXPLICIT_MODULES'] = 'NO'
     end
   end

3. Install pods (autolinks the SDK):

   cd ios && pod install

4. Add dgissdk.key to the app target's Copy Bundle Resources (see above).

5. Add an NSLocationWhenInUseUsageDescription string to Info.plist.

No AppDelegate initialization is required — the iOS module initializes itself.

Usage

import {useMemo} from 'react';
import {
  DGis,
  DgisSource,
  MapControllerOptions,
  MapView,
  useMapController,
} from '@2gis/dgis-mobile-sdk-map';

function Map() {
  // Uses the bundled `dgissdk.key` by default.
  const context = useMemo(() => DGis.createContext(), []);
  const options = useMemo(
    () =>
      new MapControllerOptions({
        sources: [DgisSource.createDgisSource(context)],
      }),
    [context],
  );

  const controllerState = useMapController(context, options);
  return <MapView controllerState={controllerState} style={{flex: 1}} />;
}