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 an access key file:

  1. Sign in to the Platform Manager.
  2. 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.
  3. Create an access key or configure an existing key for use with the mobile SDK.
  4. Download the dgissdk.key file.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.

Key usage requirements​

  • For SDK version 13.3.0 and later, specifying an App ID when creating a key is optional. Specify an App ID only if you are using earlier SDK versions or 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 alternatives for a single OS (for example, one application for the driver and another for the passenger).
    • If different SDK versions are used (Full and Map).
  • Changing the key file while the application is running is not supported. Since the key file is selected during SDK initialization, you can give them different names (by default, dgissdk.key is used). To do this, pass a key with a different name via the keySource parameter in DGis.Container.

2. Install SDK​

Swift Package Manager​

To install iOS SDK via Swift Package Manager, add a package dependency to your project. See Apple documentation for instructions on installing Swift packages.

To connect SDK, specify the URL depending on the version:

  • https://github.com/2gis/mobile-sdk-full-swift-package for the Full SDK version.
  • https://github.com/2gis/mobile-sdk-map-swift-package for the Map SDK version.

CocoaPods​

To install iOS SDK via CocoaPods, add the DGisMobileSDK dependency.

Use Swift Package Manager versioning, adding the -full or -map postfix, depending on the required SDK version.

You can view the pod specification at one of the following URLs:

  • https://github.com/2gis/mobile-sdk-full-swift-package/blob/master/DGisMobileSDK.podspec for the Full SDK version.
  • https://github.com/2gis/mobile-sdk-map-swift-package/blob/master/DGisMobileSDK.podspec for the Map SDK version.

Binary artifact​

You can download frameworks directly without using package managers. To do this, refer to the repository that contains the package specification for CocoaPods or Swift Package Manager:

  • https://github.com/2gis/mobile-sdk-full-swift-package for the Full SDK version.
  • https://github.com/2gis/mobile-sdk-map-swift-package for the Map SDK version.

The Package.swift file will contain a URL leading to downloading the SDK archive via a direct link. To navigate through versions, use git tags.

3. Initialize SDK​

  1. Create a Container object, which will store all map entities. When creating the object, specify the path to the received dgissdk.key key file in one of the following ways:

    • From Bundle.main of the application using the fromAsset() method (default way). The key must be attached to the application root:

      // Getting the key file
      let key = KeySource.fromAsset(KeyFromAsset(path: "dgissdk.key"))

      // Creating the Container
      let sdk = DGis.Container(keySource: key)

    • Specifying an absolute path to the key file using the fromFile() method:

      // Getting the key file
      let key = Bundle.main.path(forResource: "dgissdk", ofType: "key").map {
            KeySource.fromFile(KeyFromFile(path: $0))
          }

      // Creating the Container
      let sdk = DGis.Container(keySource: key)

    • Specifying a string for getting the key file using the fromString() method:

      // Getting the key file
      let key = KeySource.fromString(KeyFromString(contents: "some content"))

      // Creating the Container
      let sdk = DGis.Container(keySource: key)
    warning

    DGis.Container can be created in a single instance only. You can recreate it to free up unused resources (for example, the cache after the first map creation).

  2. Additionally, you can specify logging settings (LogOptions) and HTTP client settings (HTTPOptions) such as timeout and caching.

    // Logging settings
    let logOptions = LogOptions(systemLevel: .info)

    // HTTP client settings
    let httpOptions = HttpOptions.init()

    // Consent to personal data processing
    let personalDataCollectionOptions = PersonalDataCollectionOptions(personalDataCollectionConsent: .granted)

    // Creating the Container
    let sdk = DGis.Container(
        keySource: key,
        logOptions: logOptions,
        httpOptions: httpOptions,
        personalDataCollectionOptions: personalDataCollectionOptions
    )

Additional settings​

Vendor Config​

To override some SDK operation settings, a file in VendorConfig format is used, which is passed during SDK container initialization.

  1. Add the file to the bundle when building the application and create an instance of the File class.

    For a file added to the root of the bundle and named vendor-config.json, the code will look like this:

    let vendorConfigFile = Bundle.main.path(forResource: "vendor-config", ofType: "jsonx").map {
        VendorConfig.fromFile(VendorConfigFromFile(path: $0))
    }

  2. Pass this variable as the vendorConfigFile parameter value when initializing Container:

    let sdk = DGis.Container(
        keySource: key,
        logOptions: logOptions,
        httpOptions: httpOptions,
        vendorConfigFile: vendorConfigFile ?? .none
    )

Working with offline data​

Mobile SDK (the Full version) allows you to work with map, directory, and routing data offline from preloaded packages. This can be helpful when the network connection is low or missing.

To configure the offline mode:

  1. Contact 2GIS support to get access rights for working with offline data. You can request access to offline data for all components (map, directory, routing) or select only the required ones.

  2. Use TerritoryManager to download data files for territories where your application must work offline.

    See a code example of loading territories:

  3. Configure SDK components for working with preloaded data:

Application language​

To set the application language, pass a list of locales (Locale) to the overrideLocales() method of the LocaleManager class.

Navigator language

Depending on the selected locale, the language of sound notifications in the navigator changes.

Example of setting the English locale:

// Creating a Locale object with the specified language and region
let locale = Locale(language: "en", region: "EN")

// Setting the locale for the application
LocaleManager.instance(context: sdkContext).overrideLocales(locales: [locale])

Available language values (parameters language and region respectively):

  • ru-RU - Russian
  • en-EN - English
  • ar-AE - Arabic