设置项目 - 4.99 及更低版本

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

使用 Navigation SDK 的最低要求

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

  • Google Cloud 控制台

    启用了 Navigation SDK 的项目。如需进行预配,请咨询您的 Google Maps Platform 代表。

  • 您的应用必须以 API 级别 30 或更高级别为目标平台。

  • 如需运行使用 Navigation SDK 构建的应用,Android 设备必须安装并启用 Google Play 服务。

  • 必须向应用添加提供方说明和许可文本。

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

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

设置

  1. 在您常用的网络浏览器中,登录 Cloud 控制台并创建 Cloud 控制台项目。
  2. 在 IDE(例如 Android Studio)中,创建一个 Android 应用开发项目并记下软件包名称。
  3. 请与您的 Google Maps Platform 代表联系,以便为您的 Cloud 控制台项目提供 Navigation SDK 访问权限。
  4. 在网络浏览器中打开 Cloud 控制台信息中心,创建凭据以生成具有限制条件的 API 密钥。
  5. 在 API 密钥页面上,点击应用限制区域中的“Android 应用”。
  6. 点击添加软件包名称和指纹,然后输入开发项目的软件包名称和该密钥的 SHA-1 指纹。
  7. 点击保存。

将 Navigation SDK 添加到您的项目

Navigation SDK 可通过 Maven 或 AAR 软件包获取。创建开发项目后,您可以使用以下方法之一将 SDK 集成到项目中。

使用 Maven 获取 Navigation SDK v4.5 及更高版本(推荐)

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

  1. 将以下依赖项添加到您的 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 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 用于 4.5 版之前的 Navigation SDK,或与 Driver SDK 搭配使用

在 v4 版本的剩余时间内,您仍可通过原始 Maven 制品库使用 Navigation SDK。此库与上述版本相同,包含所有相同的更新,并在过渡期间提供与 Driver SDK 和其他库的兼容性。 使用此依赖项需要在编译时使用 gcloud 登录您的云项目。

  1. 按照 Consumer SDK 文档的前提条件部分中的说明,设置您的环境以访问 Google 的 Maven 制品库。对 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. 从共享 Google 云端硬盘下载最新版本的 Navigation SDK 并将其解压缩。如果您没有访问权限,请与您的代表联系。

  2. 在 Android Studio 中,打开一个项目,然后使用 SDK 管理器添加 Google Play 服务软件包。

  3. 从 ZIP 文件目录中,将 libs/google_navigation_navmap.aar 复制到项目的 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 脚本

  • 打开 build.gradle (Module:app) 文件,并按照以下准则更新设置,以满足 Navigation SDK 的要求,同时考虑设置优化选项。

    Navigation SDK 的必需设置

    1. 将 minSdkVersion 设置为 23 或更高。
    2. 将 targetSdkVersion 设置为 30 或更高。
    3. 添加一个可增加 javaMaxHeapSize 的 dexOptions 设置。
    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. 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 属性文件。

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

如需安装 Android 版 Secrets Gradle 插件并存储您的 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. 在顶级目录(即 secrets.properties 文件所在的文件夹)中创建 local.defaults.properties 文件,然后添加以下代码。

    MAPS_API_KEY=DEFAULT_API_KEY

    此文件的作用是为 API 密钥提供备用位置,以免在找不到 secrets.properties 文件的情况下构建失败。如果您是从省略 secrets.properties 的版本控制系统中克隆应用,而您还没有在本地创建 secrets.properties 文件来提供 API 密钥,就可能会出现构建失败。

  6. 您可以将 API 密钥添加到 AndroidManifest.xml 文件中,也可以通过编程方式提供 API 密钥。
    • 将您的 API 密钥添加到 AndroidManifest.xml:
      <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 会抛出异常。

    • 以编程方式提供 API 密钥:

      Secrets Gradle 插件会在 BuildConfig 类中提供该密钥。 在应用的初始化过程中(例如,在 Application.onCreate() 方法中),按如下方式调用该方法:

      Kotlin

      1. 添加以下 import 语句:
        import com.google.android.libraries.navigation.NavigationApi
      2. 将以下代码添加到 Application.onCreate() 方法中:
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

      Java

      1. 添加以下 import 语句:
        import com.google.android.libraries.navigation.NavigationApi;
      2. 将以下代码添加到 Application.onCreate() 方法中:
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
      注意:使用 setApiKey() 时,请注意以下几点:
      • 请提供非 null、非空的 API 密钥。
      • 在应用的生命周期内,只需调用 setApiKey() 一次。如果多次调用该方法,则会抛出 IllegalStateException。
      • 在初始化任何其他 Navigation SDK 组件(例如 Navigator)之前,请先调用 setApiKey()。
      • 您通过此方法提供的密钥会覆盖 AndroidManifest.xml 中的所有 API 密钥。
      • 使用 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 for Android,则必须在应用的法律声明部分包含提供方文字和开源许可。

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

  • NOTICE.txt
  • LICENSES.txt