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

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

Добавьте навигационный SDK в свой проект

Навигационный SDK доступен через репозиторий Google Maven . Вы можете добавить SDK в свой проект, используя конфигурацию Gradle build.gradle или Maven pom.xml .

Примечание. Этот метод несовместим с некоторыми библиотеками, которые зависят от навигационного SDK через предыдущий идентификатор артефакта. Сюда входят выпуски Driver SDK v4.4 или более ранних версий.

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

   Градл

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

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

   Мавен

   Добавьте следующее в ваш pom.xml :

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

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

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

   Градл

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

   allprojects {
           ...
           // Required: you must exclude the Google Play service Maps SDK from
           // your transitive dependencies. This is to ensure 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'
               }
           }
   }
   

   Мавен

   Добавьте следующее в ваш 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, а также рассмотрите возможность настройки параметров оптимизации.

  Необходимые настройки для навигационного SDK

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

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

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

  Добавить обессахаривание для поддержки Java8.

  • Если вы создаете свое приложение с использованием подключаемого модуля Android Gradle 4.0.0 или более поздней версии, этот подключаемый модуль расширяет поддержку использования ряда API-интерфейсов языка Java 8. Дополнительную информацию см. в разделе Поддержка очистки от сахара в Java 8 . См. приведенный ниже пример фрагмента сценария сборки, чтобы узнать, как компилировать и использовать параметры зависимостей.
  • Мы рекомендуем использовать Gradle 8.4, плагин Android Gradle версии 8.3.0 и библиотеку Desugar com.android.tools:desugar_jdk_libs_nio:2.0.3 . Эта настройка совместима с навигационным SDK для Android версии 6.0.0 и выше.
  • Библиотеку Desugar необходимо включить для модуля app и любого модуля, который напрямую зависит от навигационного SDK.

Ниже приведен пример сценария сборки 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.0.3'
}

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

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

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

Примечание. Последние системные требования и инструкции по установке см. в документации по плагину Secrets Gradle для Android на GitHub.

Чтобы установить плагин Secrets Gradle для Android в свой проект Google Maps:

1. В Android Studio откройте файл build.gradle.kts или build.gradle верхнего уровня и добавьте следующий код в элемент dependencies в buildscript .

   Котлин

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   классный

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }
   

2. Откройте файл build.gradle.kts или build.gradle уровня модуля и добавьте следующий код в элемент plugins .

   Котлин

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

   классный

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. В файле build.gradle.kts или build.gradle на уровне модуля убедитесь, что для targetSdk и compileSdk установлено значение 34.
4. Сохраните файл и синхронизируйте проект с Gradle .
5. Откройте файл secrets.properties в каталоге верхнего уровня, а затем добавьте следующий код. Замените YOUR_API_KEY своим ключом API. Сохраните свой ключ в этом файле, поскольку secrets.properties не подлежит проверке в системе контроля версий.
   Примечание. Если файл secrets.properties не существует, создайте его в той же папке, что и файл local.properties .

   NAV_API_KEY=YOUR_API_KEY

6. Сохраните файл.

7. Создайте файл local.defaults.properties в каталоге верхнего уровня, в той же папке, что и файл secrets.properties , а затем добавьте следующий код.

   Примечание. Введите код, как показано. Не заменяйте DEFAULT_API_KEY своим ключом API.

   NAV_API_KEY=DEFAULT_API_KEY

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

8. Сохраните файл.
9. В файле AndroidManifest.xml перейдите по адресу com.google.android.geo.API_KEY и обновите android:value attribute . Если тег <meta-data> не существует, создайте его как дочерний элемент тега <application> .

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Navigation SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle.kts or build.gradle file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other 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 same folder as the 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"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    классный

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the 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"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

Включите необходимую атрибуцию в свое приложение

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

Ключевой момент: чтобы включить атрибуции, добавьте их как независимый пункт меню или пункт в меню «О программе».

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

• NOTICE.txt
• LICENSES.txt

Если вы являетесь клиентом компании Mobility или Fleet Engine Delivery

Если вы являетесь клиентом Mobility или Fleet Engine Delivery, узнайте о выставлении счетов в документации Mobility. Дополнительные сведения о записи транзакций см. в разделах Настройка выставления счетов , Запись оплачиваемых транзакций , Отчеты и Запись оплачиваемых транзакций (Android) .