Navigation SDK 目前仅面向部分客户提供。如需了解详情，请与销售人员联系。

Google Maps Platform 即将推出新的地图样式设置。此次地图样式更新包括新的默认调色板，并改进了地图体验和易用性。所有地图样式都将在 2025 年 3 月自动更新。如需详细了解适用范围以及如何提前选择启用，请参阅 Google Maps Platform 的新地图样式。

此页面由 Cloud Translation API 翻译。

设置项目 - 4.99 及更低版本

本指南列出了使用 Navigation SDK for Android 的 build 配置要求。以下说明假定您已安装 Android IDE 并熟悉 Android 开发。

使用 Navigation SDK 的最低要求

这些要求适用于 Navigation SDK for Android 4.99 及更低版本。

启用了 Navigation SDK 的 Google Cloud 控制台项目。如需配置，请咨询您的 Google Maps Platform 代表。
您的应用必须以 API 级别 30 或更高级别为目标平台。
如需运行使用 Navigation SDK 构建的应用，Android 设备必须安装并启用 Google Play 服务。
必须将提供方说明和许可文本添加到应用中。

设置项目：Cloud 控制台项目和 Android 项目

您需要先创建一个 Cloud 控制台项目并添加 API 密钥凭据，然后才能构建或测试应用。项目必须配置才能访问 Navigation SDK。Cloud 控制台项目中的所有键都拥有与 Navigation SDK 相同的访问权限。一个密钥可以有多个与之关联的开发项目。如果您已有控制台项目，则可以向当前项目添加一个密钥。

要设置

在您偏好的网络浏览器中，登录 Cloud 控制台，然后创建 Cloud 控制台项目。
在您的 IDE（例如 Android Studio）中，创建一个 Android 应用开发项目并记下软件包名称。
请与您的 Google Maps Platform 代表联系，让其访问您的 Cloud 控制台项目的 Navigation SDK。
在网络浏览器中的 Cloud 控制台信息中心内，创建凭据以生成设有限制的 API 密钥。
在 API 密钥页面上，点击应用限制部分中的“Android 应用”。
点击添加软件包名称和指纹，然后输入开发项目的软件包名称以及该密钥的 SHA-1 指纹。
点击保存。

将 Navigation SDK 添加到您的项目

Navigation SDK 可通过 Maven 或 AAR 软件包的形式提供。创建开发项目后，您可以使用以下方法之一将 SDK 集成到其中。

将 Maven 用于 Navigation SDK v4.5 及更高版本（推荐）

以下示例使用 google() Maven 制品库，这是将 Navigation SDK 添加到项目的最简单、推荐方法

将以下依赖项添加到您的 Gradle 或 Maven 配置中，并将 VERSION_NUMBER 占位符替换为所需的 Navigation SDK for 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. 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'
       }
   }
}

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 v4.5 之前的版本，或将 Maven 与驱动程序 SDK 结合使用

在 v4 的其余版本中，Navigation SDK 可继续通过原始 Maven 制品库提供。这是一个库，包含与上述版本相同的所有更新，并在转换期间与驱动程序 SDK 和其他库兼容。如需使用此依赖项，您需要在编译时通过 gcloud 登录 Cloud 项目。

按照 Consumer SDK 文档的前提条件部分所述，设置您的环境以访问 Google 的 Maven 制品库。对 Navigation SDK 的访问权限通过工作区组控制。

将以下依赖项添加到您的 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. 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'
       }
   }
}

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。以下说明假定您的 IDE 使用的是 Android Studio。

从共享的 Google 云端硬盘下载最新版本的 Navigation SDK，并将其解压缩。如果您没有访问权限，请联系您的代表。
在 Android Studio 中，打开项目并使用 SDK 管理器添加 Google Play 服务软件包。
从 zip 文件目录中，将 libs/google_navigation_navmap.aar 复制到项目的 app/libs 目录中。

将以下内容添加到模块级 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. 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'
        }
    }
}

配置构建

创建项目后，您可以配置设置，以便成功构建和使用 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. 为 Navigation SDK 添加 repositories 和 dependencies。
6. 将依赖项中的版本号替换为最新的可用版本。
可缩短构建时间的可选设置
- 使用 R8/ProGuard 启用代码缩减和资源缩减，从依赖项中移除未使用的代码和资源。如果 R8/ProGuard 步骤的运行时间过长，请考虑启用 MultiDex 以进行开发工作。
- 减少 build 中包含的语言翻译数量：在开发期间为一种语言设置 resConfigs。对于最终 build，请为您实际使用的语言设置 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. Ensure 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 文件中。如需详细了解 secrets.properties 文件，请参阅 Gradle 属性文件。

为了简化此任务，建议您使用 Android 版 Secrets Gradle 插件。

如需在 Google 地图项目中安装 Android 版 Secret Gradle 插件，请执行以下操作：

在 Android Studio 中，打开顶级 build.gradle 或 build.gradle.kts 文件，并将以下代码添加到 buildscript 下的 dependencies 元素中。

Groovy

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

Kotlin

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

打开模块级 build.gradle 文件，并将以下代码添加到 plugins 元素中。

Groovy

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

Kotlin

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

在模块级 build.gradle 文件中，请务必将 targetSdk 和 compileSdk 设置为 34。
保存文件并将项目与 Gradle 同步。
在顶级目录中打开 secrets.properties 文件，然后添加以下代码。将 YOUR_API_KEY 替换为您的 API 密钥。secrets.properties 不会签入版本控制系统，因此请将您的密钥存储在此文件中。
注意：如果 secrets.properties 文件不存在，请在 local.properties 文件所在的文件夹中创建该文件。
```
MAPS_API_KEY=YOUR_API_KEY
```
保存文件。
在顶级目录（即 secrets.properties 文件所在的文件夹）中创建 local.defaults.properties 文件，然后添加以下代码。

注意：请按下方所示输入代码。不要将 DEFAULT_API_KEY 替换为您的 API 密钥。
```
MAPS_API_KEY=DEFAULT_API_KEY
```
此文件的作用是为 API 密钥提供备用位置，以免在找不到 secrets.properties 文件的情况下构建失败。如果您是从省略 secrets.properties 的版本控制系统中克隆应用，而您还没有在本地创建 secrets.properties 文件来提供 API 密钥，就可能会出现构建失败。
保存文件。
在 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.

In Android Studio, open your module-level build.gradle or build.gradle.kts 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.

Groovy

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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.*"
}

Kotlin

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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 for Android，则必须在应用的法律声明部分包含提供方说明文本和开源许可。

您可以在 Navigation SDK for Android 的 ZIP 文件中找到所需的提供方说明文本和开源许可：

NOTICE.txt
LICENSES.txt