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

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

此页面由 Cloud Translation API 翻译。

设置您的 Android Studio 项目

Navigation SDK 可通过 Maven 获取。创建开发项目后，您可以使用以下任一方法将 SDK 集成到该项目中。

将 Maven 用于 Navigation SDK（推荐）

以下示例使用了 google() Maven 制品库，这是向项目添加 Navigation SDK 的最简单且推荐的方式。

将以下依赖项添加到您的 Gradle 或 Maven 配置中，并将VERSION_NUMBER占位符替换为所需的 Navigation SDK 版本。
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>
```
注意：如果您是从原服务升级的移动服务客户和工件名称以及 com.google.cloud.artifactregistry.gradle-plugin 插件不再适用。

如果您有任何使用 Maps SDK 的依赖项，则必须在每个依赖于 Maps SDK 的声明依赖项中排除该依赖项。

Gradle

将以下内容添加到顶级 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>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 设置为 23 或更高版本。
2. 将 targetSdkVersion 设置为 34 或更高版本。
3. 添加用于增加 javaMaxHeapSize 的 dexOptions 设置。
4. 设置其他库的位置。
5. 为 Navigation SDK 添加了 repositories 和 dependencies。
6. 将依赖项中的版本号替换为最新的可用版本。
用于缩短构建时间的可选设置
- 启用代码压缩和资源缩减使用 R8/ProGuard 从依赖项中移除未使用的代码和资源。如果 R8/ProGuard 步骤运行时间过长，请考虑为开发工作启用 multidex。
- 减少 build 中包含的语言翻译数量：设置在开发期间针对一种语言提供 resConfigs。对于最终版本为您实际使用的语言设置 resConfigs。默认情况下，Gradle 包含 Navigation SDK。
添加了 Java8 脱糖支持
- 如果您使用 Android Gradle 插件 4.0.0 或此插件扩展了对使用多种 Java 8 语言的支持， API。请参阅 Java 8 脱糖支持。请参阅下面的示例 build 脚本代码段，了解编译和依赖项选项。
- 我们建议使用 Gradle 8.4（Android Gradle 插件版本） 8.3.0 和脱糖库 com.android.tools:desugar_jdk_libs_nio:2.0.3。此设置与 Android 版 Navigation SDK 6.0.0 及更高版本兼容。
- 需要为 app 模块以及任何模块直接依赖于 Navigation 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 属性文件。

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

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

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

Kotlin

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

Groovy

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

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

Kotlin

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

Groovy

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

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

注意：请按下方所示输入代码。不要将 DEFAULT_API_KEY 替换为您的 API 密钥。
```
NAV_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}" />
```
注意：建议使用 com.google.android.geo.API_KEY 作为 API 密钥的元数据名称。使用此名称的密钥可用于向多个 Android 平台上基于 Google 地图的 API，包括适用于 Android 的 Navigation SDK。为了实现向后兼容性，该 API 还支持名称 com.google.android.maps.v2.API_KEY。此旧版名称只允许向 Android Maps API v2 进行身份验证。应用只能指定其中一个 API 密钥元数据名称。如果同时指定了两者，则 API 会抛出异常。

在 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 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.*"
}

Groovy

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 for Android，则必须添加应用的法律声明中的署名文本和开源许可部分。

您可以在 Android 版 Navigation SDK zip 文件中找到所需的归属文字和开源许可：

NOTICE.txt
LICENSES.txt

如果您是 Mobility 或 Fleet Engine Delivery 客户

如果您是 Mobility 或车队引擎配送服务客户，请参阅 Mobility 文档了解结算事宜。如需详细了解如何记录交易，请参阅设置结算、记录可结算的交易、报告和记录可结算的交易 (Android)。