Как настроить проект (версия 4.99 и более ранние)

В этом руководстве перечислены требования к конфигурации сборки для использования Navigation SDK для Android. В инструкциях предполагается, что у вас установлена интегрированная среда разработки Android и вы знакомы с разработкой для Android.

Минимальные требования для использования Navigation SDK

Эти требования относятся к Navigation SDK для Android версии 4.99 и более ранних.

  • Консоль Google Cloud

    с включенным Navigation SDK. Чтобы получить доступ, обратитесь к представителю платформы Google Карт.

  • Целевой уровень API в вашем приложении должен быть не ниже 30.

  • Чтобы запустить приложение, созданное с помощью Navigation SDK, на устройстве Android должны быть установлены и включены сервисы Google Play.

  • В приложение необходимо добавить текст с указанием авторства и лицензии.

Настройте проекты: проект Cloud Console и проект для Android

Прежде чем создавать или тестировать приложение, необходимо создать проект в Cloud Console и добавить учетные данные ключа API. Для доступа к Navigation SDK в проекте должна быть настроена инициализация. Всем ключам в проекте Cloud Console предоставляется одинаковый доступ к Navigation SDK. С одним ключом может быть связано несколько проектов. Если у вас уже есть проект в консоли, вы можете добавить ключ в него.

Как настроить

  1. В браузере войдите в Cloud Console и создайте проект Cloud Console.
  2. В интегрированной среде разработки, например Android Studio, создайте проект приложения для Android и запишите название пакета.
  3. Обратитесь к представителю платформы Google Карт, чтобы получить доступ к Navigation SDK для проекта в Cloud Console.
  4. На панели управления Cloud Console в браузере создайте учетные данные, чтобы сгенерировать ключ API с ограничениями.
  5. На странице Ключ API в разделе Ограничения для приложений выберите "Приложения для Android".
  6. Нажмите Добавить название пакета и цифровой отпечаток, а затем введите название пакета проекта разработки и цифровой отпечаток SHA-1 для этого ключа.
  7. Нажмите Сохранить.

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

Navigation SDK доступен в Maven или в виде пакета AAR. После создания проекта разработки вы можете интегрировать в него SDK, используя один из следующих подходов.

Используйте Maven для Navigation SDK версии 4.5 и более поздних (рекомендуется)

Ниже описано, как добавить Navigation SDK в проект с помощью репозитория Maven google(). Это самый простой и рекомендуемый способ.

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

    Gradle

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

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

    Если вы переходите с исходного репозитория Maven, обратите внимание, что названия группы и артефакта изменились, а плагин com.google.cloud.artifactregistry.gradle-plugin больше не нужен.

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

    allprojects {
    ...
    // Required: you must exclude the Google Play service Maps SDK from
    // your transitive dependencies to make nsure 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>com.google.android.libraries.navigation</groupId>
         <artifactId>navigation</artifactId>
         <version>VERSION_NUMBER</version>
    </dependency>
    </dependencies>
    

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

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

Используйте Maven для Navigation SDK до версии 4.5 или с Driver SDK

Navigation SDK по-прежнему доступен в исходном репозитории Maven для всех версий 4. Это та же библиотека со всеми обновлениями, что и в версии выше. Она обеспечивает совместимость с Driver SDK и другими библиотеками во время перехода. Чтобы использовать эту зависимость, при компиляции необходимо войти в облачный проект с помощью gcloud.

  1. Настройте среду для доступа к репозиторию Maven от Google, как описано в разделе Предварительные требования документации по Consumer SDK. Доступ к Navigation SDK контролируется через группу рабочей области.
  2. Добавьте в конфигурацию Gradle или Maven следующую зависимость, заменив плейсхолдер VERSION_NUMBER версией Navigation SDK.

    Gradle

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

    dependencies {
    ...
    implementation 'com.google.android.maps:navsdk:VERSION_NUMBER'
    }
    

    Добавьте в файл 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>com.google.android.maps</groupId>
         <artifactId>navsdk</artifactId>
         <version>VERSION_NUMBER</version>
    </dependency>
    </dependencies>
    

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

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

Использование скачанного пакета AAR (не рекомендуется)

Navigation SDK также доступен в виде пакета AAR. После создания проекта разработки можно интегрировать SDK. В этих инструкциях предполагается, что вы используете Android Studio в качестве IDE.

  1. Скачайте последнюю версию Navigation SDK с общего Google Диска и распакуйте ее. Если у вас нет доступа, обратитесь к своему представителю.

  2. В Android Studio откройте проект и добавьте пакет сервисов Google Play с помощью SDK Manager.

  3. Скопируйте файл libs/google_navigation_navmap.aar из каталога ZIP-файла в каталог app/libs проекта.

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

    implementation(name: 'google_navigation_navmap', ext: 'aar')
    

    Добавьте в файл 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'
           }
       }
    }
    

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

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

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

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

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

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

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

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

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

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

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

apply plugin: 'com.android.application'
apply plugin: 'com.google.cloud.artifactregistry.gradle-plugin'

ext {
    androidxVersion = "1.0.0"
    lifecycle_version = "1.1.1"
}

android {
    compileSdkVersion 30
    buildToolsVersion '28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 30
        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 {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

// This tells Gradle where to look to find additional libraries - in this case, the
// google_navigation_navmap.aar file.
repositories {
    flatDir {
        dirs 'libs'
    }
    google()

    // Required for accessing the Navigation SDK on Google's Maven repository.
    maven {
        url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
    }
}

dependencies {
    // Include the Google Navigation SDK
    implementation 'com.google.android.maps:navsdk:4.4.0'

    // The included AAR file under libs can be used instead of the Maven repository.
    // Uncomment the line below and comment out the previous dependency to use
    // the AAR file instead. Make sure that you add the AAR file to the libs directory.
    // implementation(name: 'google_navigation_navmap', ext: 'aar')

    // These dependencies are required for the Navigation SDK to function
    // properly at runtime.
    implementation 'org.chromium.net:cronet-fallback:69.3497.100'
    // Optional for Cronet users:
    // implementation 'org.chromium.net:cronet-api:69.3497.100'
    implementation 'androidx.appcompat:appcompat:${androidxVersion}'
    implementation 'androidx.cardview:cardview:${androidxVersion}'
    implementation 'com.google.android.material:material:${androidxVersion}'
    implementation 'androidx.mediarouter:mediarouter:${androidxVersion}'
    implementation 'androidx.preference:preference:${androidxVersion}'
    implementation 'androidx.recyclerview:recyclerview:${androidxVersion}'
    implementation 'androidx.legacy:legacy-support-v4:${androidxVersion}'
    implementation 'com.github.bumptech.glide:glide:4.9.0'
    implementation 'com.github.bumptech.glide:okhttp-integration:4.9.0'
    implementation 'android.arch.lifecycle:common-java8:$lifecycle_version'
    implementation 'com.android.support:multidex:1.0.3'
    implementation 'com.google.android.datatransport:transport-api:2.2.0'
    implementation 'com.google.android.datatransport:transport-backend-cct:2.2.0'
    implementation 'com.google.android.datatransport:transport-runtime:2.2.0'
    implementation 'joda-time:joda-time:2.9.9'
    annotationProcessor 'androidx.annotation:annotation:1.1.0'
    annotationProcessor 'com.github.bumptech.glide:compiler:4.9.0'
}

Как добавить в приложение ключ 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