本指南列出了使用 Navigation SDK for Android 的 build 配置要求。以下说明假定您已安装 Android IDE 并且熟悉 Android 开发。
使用 Navigation SDK 的最低要求
这些要求适用于 Navigation SDK for Android 4.99 及更低版本。
启用了 Navigation SDK 的 Google Cloud Console 项目。如需预配,请咨询您的 Google Maps Platform 代表。
您的应用必须以 API 级别 30 或更高级别为目标平台。
如需运行使用 Navigation SDK 构建的应用,Android 设备必须安装并启用 Google Play 服务。
必须向应用添加提供方说明和许可文本。
设置您的项目:Cloud 控制台项目和 Android 项目
您需要先创建 Cloud 控制台项目并添加 API 密钥凭据,然后才能构建或测试应用。项目必须经过预配才能访问 Navigation SDK。Cloud Console 项目中的所有密钥都将获得对 Navigation SDK 的相同访问权限。一个密钥可以与多个开发项目相关联。如果您已有控制台项目,则可以向当前项目添加密钥。
要进行设置
- 在您喜爱的网络浏览器中,登录 Cloud Console 并创建 Cloud Console 项目。
- 在 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 4.5 之前的版本或 Driver SDK 搭配使用
在其余 v4 版本中,Navigation SDK 仍可通过原始 Maven 制品库获取。这是一个与上述版本相同的库,其中包含的所有更新均与上述版本相同,并且可在过渡期间与驱动程序 SDK 和其他库兼容。要使用此依赖项,请在编译时通过 gcloud
登录您的云项目。
- 按照消费者 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。以下说明假定您使用 Android Studio 作为 IDE。
从共享的 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 脚本
打开
build.gradle (Module:app)
文件,并按照以下准则更新设置,以满足 Navigation SDK 的要求,同时考虑设置优化选项。Navigation SDK 的必需设置
- 将
minSdkVersion
设置为 23 或更高版本。 - 将
targetSdkVersion
设置为 30 或更高版本。 - 添加用于增加
javaMaxHeapSize
的dexOptions
设置。 - 设置其他库的位置。
- 为 Navigation SDK 添加
repositories
和dependencies
。 - 将依赖项中的版本号替换为最新的可用版本。
用于缩短构建时间的可选设置
- 将
以下是应用的 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 版 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
不会签入版本控制系统,因此请将您的密钥存储在此文件中。NAV_API_KEY=YOUR_API_KEY
- 保存文件。
-
在顶级目录(即
secrets.properties
文件所在的文件夹)中创建local.defaults.properties
文件,然后添加以下代码。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(包括 Navigation SDK for Android)的身份验证。为了实现向后兼容性,该 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