Настройте проект Android Studio

На этой странице рассказывается, как интегрировать Navigation SDK в проект разработки.

Как добавить Navigation SDK в проект

Navigation SDK доступен в репозитории Google Maven. Добавить SDK в проект можно с помощью конфигурации Gradle build.gradle или Maven pom.xml.

  1. Добавьте в конфигурацию Gradle или Maven следующую зависимость, заменив плейсхолдер VERSION_NUMBER нужной версией Navigation SDK для Android.

    Gradle

    Добавьте в файл build.gradle на уровне модуля следующий код:

    dependencies {
        ...
        implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
}

    Maven

    Добавьте в файл pom.xml следующий код:

    <dependencies>
  ...
  <dependency>
    <groupId>com.google.android.libraries.navigation</groupId>
    <artifactId>navigation</artifactId>
    <version>VERSION_NUMBER</version>
  </dependency>
</dependencies>

  2. Если у вас есть зависимости, использующие Maps SDK, вам нужно исключить зависимость в каждой объявленной зависимости, которая полагается на Maps SDK.

    Gradle

    Добавьте в файл build.gradle верхнего уровня следующий код:

    allprojects {
        ...
        // Required: you must exclude the Google Play service Maps SDK from
        // your transitive dependencies to make sure there won't be
        // multiple copies of Google Maps SDK in your binary, as the Navigation
        // SDK already bundles the Google Maps SDK.
        configurations {
            implementation {
                exclude group: 'com.google.android.gms', module: 'play-services-maps'
            }
        }
}

    Maven

    Добавьте в файл pom.xml следующий код:

    <dependencies>
  <dependency>
  <groupId>project.that.brings.in.maps</groupId>
  <artifactId>MapsConsumer</artifactId>
  <version>1.0</version>
    <exclusions>
      <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication-->
      <exclusion>  <!-- declare the exclusion here -->
        <groupId>com.google.android.gms</groupId>
        <artifactId>play-services-maps</artifactId>
      </exclusion>
    </exclusions>
  </dependency>
</dependencies>

Настройте сборку

После создания проекта вы можете настроить параметры для успешной сборки и использования Navigation SDK.

Обновление местных объектов

  • В папке Gradle Scripts откройте файл local.properties и добавьте android.useDeprecatedNdk=true.

Обновите скрипт сборки Gradle

  • Откройте файл build.gradle (Module:app) и измените настройки в соответствии с требованиями Navigation SDK, следуя приведенным ниже инструкциям. Также рекомендуем задать параметры оптимизации.

    Обязательные настройки для Navigation SDK

    1. Задайте для параметра minSdkVersion значение 24 или выше.
    2. Задайте для параметра targetSdkVersion значение 36 или выше.
    3. Добавьте настройку dexOptions, которая увеличивает javaMaxHeapSize.
    4. Укажите местоположение дополнительных библиотек.
    5. Добавьте repositories и dependencies для Navigation SDK.
    6. Замените номера версий в зависимостях на последние доступные версии.

    Дополнительные настройки для сокращения времени сборки

    • Включите сокращение кода и ресурсов с помощью R8/ProGuard, чтобы удалить неиспользуемый код и ресурсы из зависимостей. Если этап R8/ProGuard занимает слишком много времени, попробуйте включить multidex для разработки.
    • Уменьшите количество языков, на которые переведено приложение. Для этого во время разработки задайте значение resConfigs для одного языка. Для финальной сборки задайте resConfigs для языков, которые вы действительно используете. По умолчанию Gradle включает строки ресурсов для всех языков, поддерживаемых Navigation SDK.

    Добавьте десахаризацию для поддержки Java 8

    • Если вы создаете приложение с помощью плагина Android Gradle версии 4.0.0 или более поздней, то можете использовать ряд API языка Java 8. Подробную информацию можно найти в статье Поддержка десахаризации Java 8. Ниже приведен пример скрипта сборки с параметрами компиляции и зависимостей.
    • Используйте версии Gradle, плагина Android Gradle (AGP) и библиотеки Desugar, которые соответствуют вашей версии Navigation SDK. См. таблицу ниже.
    • Библиотеку Desugar необходимо включить для модуля app и любого модуля, который напрямую зависит от Navigation SDK.

В таблице ниже перечислены версии Gradle, AGP и библиотеки Desugar, необходимые для каждой версии Navigation SDK.

Версия Navigation SDK Версия Gradle Версия AGP Библиотека дешугаринга
8.0.0 и выше 9.1.0 9.0.1 com.android.tools:desugar_jdk_libs_nio:2.1.5
7.7.0–7.9.0 8.13 8.13.2 com.android.tools:desugar_jdk_libs_nio:2.1.5
7.3.0–7.6.0 8.11.1 8.10.0 com.android.tools:desugar_jdk_libs_nio:2.0.3

Ниже приведен пример скрипта сборки Gradle для приложения. Проверьте обновленные наборы зависимостей в примерах приложений, так как версия Navigation SDK, которую вы используете, может немного отличаться от описанной в этой документации.

apply plugin: 'com.android.application'

ext {
    navSdk = "__NAVSDK_VERSION__"
}

android {
    compileSdk 33
    buildToolsVersion='28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
        // Set this to the languages you actually use, otherwise you'll include resource strings
        // for all languages supported by the Navigation SDK.
        resConfigs "en"
        multiDexEnabled true
    }

    dexOptions {
        // This increases the amount of memory available to the dexer. This is required to build
        // apps using the Navigation SDK.
        javaMaxHeapSize "4g"
    }
    buildTypes {
        // Run ProGuard. Note that the Navigation SDK includes its own ProGuard configuration.
        // The configuration is included transitively by depending on the Navigation SDK.
        // If the ProGuard step takes too long, consider enabling multidex for development work
        // instead.
        all {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

repositories {
    // Navigation SDK for Android and other libraries are hosted on Google's Maven repository.
    google()
}

dependencies {
    // Include the Google Navigation SDK.
    // Note: remember to exclude Google Play service Maps SDK from your transitive
    // dependencies to avoid duplicate copies of the Google Maps SDK.
    api "com.google.android.libraries.navigation:navigation:${navSdk}"

    // Declare other dependencies for your app here.

    annotationProcessor "androidx.annotation:annotation:1.7.0"
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs_nio:2.1.5'
}

Как добавить в приложение ключ API

В этом разделе рассказывается, как настроить безопасный вызов ключа API вашим приложением. Вводить ключ API в систему управления версиями нежелательно, поэтому мы рекомендуем хранить его в файле secrets.properties, который находится в корневом каталоге проекта и не проверяется системами контроля версий. Подробные сведения о файлах свойств Gradle можно найти в описании файлов свойств Gradle.

Чтобы упростить работу, используйте плагин Secrets Gradle для Android.

Чтобы установить плагин Secrets Gradle для Android и настроить хранение ключа API, выполните следующие действия:

  1. В Android Studio откройте файл build.gradle.kts или build.gradle верхнего уровня и добавьте в блок plugins приведенный ниже код.

    Kotlin

    plugins {
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
}

    Groovy

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
  2. Откройте файл build.gradle.kts или build.gradle уровня модуля и добавьте в элемент plugins приведенный ниже код.

    Kotlin

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}

    Groovy

    plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. Если вы используете Android Studio, синхронизируйте проект с Gradle.
  4. Откройте файл secrets.properties в каталоге верхнего уровня и добавьте приведенный ниже код. Укажите вместо YOUR_API_KEY свой ключ API. Добавьте secrets.properties в файл .gitignore (или исключите его из системы управления версиями другим способом), чтобы ключ API не попал в систему управления версиями. 
    MAPS_API_KEY=YOUR_API_KEY

  5. Создайте файл local.defaults.properties в каталоге верхнего уровня (там же, где хранится файл secrets.properties), а затем добавьте указанный ниже код.

    MAPS_API_KEY=DEFAULT_API_KEY

    Этот файл служит запасным хранилищем ключа API, чтобы обеспечить выполнение сборки, даже если система не обнаружит файл secrets.properties. Так может произойти, если вы скопируете приложение из системы управления версиями, игнорирующей файл secrets.properties, и не создадите secrets.properties с ключом API локально.

  6. Вы можете добавить ключ API в файл AndroidManifest.xml или указать его программно.
    • Добавьте ключ API в файл AndroidManifest.xml: 
      <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

      Примечание. Рекомендуемое имя метаданных для ключа API – com.google.android.geo.API_KEY. Ключ с таким именем может использоваться для аутентификации нескольких API Google Карт для Android, включая Navigation SDK для Android. Для обеспечения обратной совместимости API также поддерживает имя com.google.android.maps.v2.API_KEY. Это устаревшее имя обеспечивает аутентификацию только для Android Maps API версии 2. В приложении можно указать только одно из значений ключа android:name. Если указаны оба имени, API вызывает исключение.

    • Укажите ключ API программно:

      Плагин Secrets Gradle делает ключ доступным в классе BuildConfig. При инициализации приложения (например, в методе Application.onCreate()) вызовите метод следующим образом:

      Kotlin

      1. Добавьте следующие операторы импорта: 
        import com.google.android.libraries.navigation.NavigationApi
      2. Добавьте в метод Application.onCreate() следующий код: 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

      Java

      1. Добавьте следующие операторы импорта: 
        import com.google.android.libraries.navigation.NavigationApi;
      2. Добавьте в метод Application.onCreate() следующий код: 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
      Примечание. При использовании setApiKey() учитывайте следующее:
      • Укажите ключ API, который не является нулевым или пустым.
      • Вызывайте setApiKey() только один раз за время работы приложения. Если вызвать метод несколько раз, он выдаст ошибку IllegalStateException.
      • Вызовите setApiKey() перед инициализацией других компонентов Navigation SDK, например Navigator.
      • Ключ, указанный в этом методе, переопределяет любой ключ API в AndroidManifest.xml.
      • Используйте Navigation SDK версии 7.6 или более поздней.

  7. В Android Studio откройте файл build.gradle.kts или build.gradle на уровне модуля и измените свойство secrets. Если свойство secrets отсутствует, добавьте его.

    Измените свойства плагина, чтобы задать для propertiesFileName значение "secrets.properties", а для defaultPropertiesFileName – "local.defaults.properties". Также можно задать другие свойства.

    Kotlin

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"
}

    Groovy

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"
}

Добавьте в приложение необходимые атрибуты

Если вы используете в приложении Navigation SDK для Android, обязательно включите текст атрибуции и лицензии на ПО с открытым исходным кодом в раздел юридической информации.

Текст атрибуции и лицензии на ПО с открытым исходным кодом можно найти в ZIP-файле Navigation SDK для Android:

  • NOTICE.txt
  • LICENSES.txt

Если вы используете Mobility или Fleet Engine Deliveries

Если вы используете Mobility или Fleet Engine Deliveries, ознакомьтесь с информацией об оплате в документации по Mobility. Дополнительную информацию о регистрации транзакций можно найти в статьях Как настроить платежные данные, Как регистрировать платные транзакции, Отчеты и Как регистрировать платные транзакции (Android).

Зависимости, добавленные вручную (не Gradle/Maven)

Если ваша система сборки не разрешает транзитивные зависимости (например, Bazel) или если вы интегрируете AAR вручную, вам необходимо добавить эти зависимости в свой проект. Gradle и Maven разрешают их автоматически.

  • androidx.datastore:datastore-core
  • androidx.datastore:datastore-guava
  • com.google.guava:listenablefuture
  • androidx.concurrent:concurrent-futures