Перейти к основному содержимому

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

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

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

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

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

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

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

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

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

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

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

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

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

Swift Package Manager​

Чтобы установить iOS SDK через Swift Package Manager, добавьте в проект пакетную зависимость. См. инструкции по установке Swift-пакетов в документации Apple.

Для подключения SDK укажите URL в зависимости от версии:

  • https://github.com/2gis/mobile-sdk-full-swift-package — для версии SDK Full.
  • https://github.com/2gis/mobile-sdk-map-swift-package — для версии SDK Map.

CocoaPods​

Чтобы установить iOS SDK через CocoaPods, добавьте зависимость DGisMobileSDK.

Используйте версионирование из Swift Package Manager, при этом добавьте постфикс -full или -map в зависимости от необходимой версии SDK.

Спецификацию пода вы можете посмотреть по одному из следующих URL:

  • https://github.com/2gis/mobile-sdk-full-swift-package/blob/master/DGisMobileSDK.podspec — для версии SDK Full.
  • https://github.com/2gis/mobile-sdk-map-swift-package/blob/master/DGisMobileSDK.podspec — для версии SDK Map.

Бинарный артефакт​

Вы можете загрузить фреймворки напрямую, не используя пакетные менеджеры. Для этого обратитесь к репозиторию, содержащему спецификацию пакетов для CocoaPods или Swift Package Manager:

  • https://github.com/2gis/mobile-sdk-full-swift-package — для версии SDK Full.
  • https://github.com/2gis/mobile-sdk-map-swift-package — для версии SDK Map.

В файле Package.swift будет указан URL, ведущий на загрузку архива с SDK по прямой ссылке. Для навигации по версиям используйте теги git.

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

  1. Создайте специальный объект Container, который будет хранить все сущности, связанные с картой. При создании объекта укажите путь до полученного файла ключа dgissdk.key одним из способов:

    • Из Bundle.main приложения с помощью метода fromAsset() (способ по умолчанию). Ключ должен быть прикреплён к корню приложения:

      // Получение файла ключа
      let key = KeySource.fromAsset(KeyFromAsset(path: "dgissdk.key"))

      // Создание контейнера
      let sdk = DGis.Container(keySource: key)

    • C указанием абсолютного пути до файла ключа с помощью метода fromFile():

      // Получение файла ключа
      let key = Bundle.main.path(forResource: "dgissdk", ofType: "key").map {
            KeySource.fromFile(KeyFromFile(path: $0))
          }

      // Создание контейнера
      let sdk = DGis.Container(keySource: key)

    • С указанием строки для получения файла ключа с помощью метода fromString():

      // Получение файла ключа
      let key = KeySource.fromString(KeyFromString(contents: "some content"))

      // Создание контейнера
      let sdk = DGis.Container(keySource: key)
    предупреждение

    DGis.Container может быть создан в единственном экземпляре. Вы можете его пересоздать, чтобы освободить неиспользуемые ресурсы (например, кеш после первого создания карты).

  2. Дополнительно вы можете указать настройки журналирования (LogOptions) и настройки HTTP-клиента (HTTPOptions), такие как время ожидания ответа и кеширование.

    // Настройки журналирования
    let logOptions = LogOptions(systemLevel: .info)

    // Настройки HTTP-клиента
    let httpOptions = HttpOptions.init()

    // Настройки сбора анонимной статистики использования
    let personalDataCollectionOptions = PersonalDataCollectionOptions(personalDataCollectionConsent: .granted)

    // Создание контейнера
    let sdk = DGis.Container(
        keySource: key,
        logOptions: logOptions,
        httpOptions: httpOptions,
        personalDataCollectionOptions: personalDataCollectionOptions
    )

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

Vendor Config​

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

  1. Добавьте файл в формате VendorConfig в бандл при сборке приложения и создайте экземпляр класса File.

    Для файла, добавленного в корень бандла и имеющего имя vendor-config.json, код будет выглядеть так:

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

  2. Передайте созданную переменную в качестве значения параметра vendorConfigFile при инициализации Container:

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

Работа с офлайн-данными​

Мобильный SDK (версия Full) позволяет работать с данными карты, справочника и навигатора офлайн из предварительно загруженных пакетов. Это может быть полезно в условиях плохой связи или при её полном отсутствии.

Чтобы настроить работу в режиме офлайн:

  1. Обратитесь в отдел продаж 2ГИС, чтобы получить права на работу с офлайн-данными. Вы можете запросить права на офлайн-данные всех компонентов (карта, справочник, построение маршрутов) или выбрать только необходимые.

  2. Скачайте файлы с данными для территорий, где необходима офлайн-работа приложения, через TerritoryManager.

    См. пример кода для загрузки территории:

  3. Настройте компоненты SDK для работы с предзагруженными данными:

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

Чтобы установить язык приложения, передайте список локалей (Locale) в методе overrideLocales() класса LocaleManager.

Язык навигатора

В зависимости от выбранной локали меняется язык звуковых оповещений в навигаторе.

Пример установки англоязычной локали:

// Создание объекта Locale с указанием языка и региона
let locale = Locale(language: "en", region: "EN")

// Установка локали для приложения
LocaleManager.instance(context: sdkContext).overrideLocales(locales: [locale])

Доступные значения параметров language и region:

languageregion
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.