設定專案

本指南列出 Android 5.0.0 以上版本的 Navigation SDK 建構設定需求。

此處的操作說明假設您已安裝 Android IDE，且熟悉 Android 開發作業。

使用 Navigation SDK 的最低需求

這些規定適用於適用於 Android 5.0.0 以上版本的 Navigation SDK。

  • 已啟用 Navigation SDK 的 Google Cloud 控制台專案。如要建立帳戶，請洽詢 Google 地圖平台代表。

  • 您的應用程式必須按照下列說明指定 Android 版本：

    • target 版本必須為 Android 13 (API 級別 33) 以上版本。
    • 「最低」版本必須為 Android 6 (API 級別 23) 以上版本。

  • 如要執行使用 Navigation SDK 建構的應用程式，Android 裝置必須符合下列需求：

  • 必須在應用程式中加入作者資訊和授權文字。

設定專案：Cloud 控制台專案和 Android 專案

建構或測試應用程式之前，您必須先建立 Cloud 控制台專案，並新增 API 金鑰憑證。專案必須具備佈建功能才能存取 Navigation SDK。Cloud 控制台專案中的所有金鑰都會獲得與 Navigation SDK 相同的存取權。一個金鑰可以有多個相關聯的開發專案。如果您已有主控台專案，就可以將金鑰新增至目前的專案。

設定

  1. 在您常用的網路瀏覽器中，登入 Cloud 控制台並建立 Cloud 控制台專案。
  2. 在 IDE (例如 Android Studio) 中，建立 Android 應用程式開發專案，並記下套件名稱。
  3. 如要為 Cloud 控制台專案提供 Navigation SDK 存取權，請與 Google 地圖平台代表聯絡。
  4. 在網路瀏覽器的 Cloud 控制台資訊主頁中建立憑證，以便產生設有限制的 API 金鑰。
  5. 在「API 金鑰」頁面上，按一下「應用程式限制」區域中的「Android 應用程式」。
  6. 按一下「Add the package name and fingerprint」，然後輸入開發專案的套件名稱以及該金鑰的 SHA-1 指紋。
  7. 點按「儲存」。

在專案中新增 Navigation SDK

您可以透過 Maven 使用 Navigation SDK。建立開發專案後，您可以使用下列其中一種方法將 SDK 整合至其中。

下方會使用 google() Maven 存放區，這是在專案中新增 Navigation SDK 最簡單的建議方法。

  1. 將以下依附元件新增至 Gradle 或 Maven 設定，將 VERSION_NUMBER 預留位置替換成 Android 適用的 Navigation SDK 所需版本。

    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>

設定建構

建立專案後，您可以調整設定，確保順利建構並使用 Navigation SDK。

更新本機資源

  • 在「Gradle Scripts」資料夾中開啟 local.properties 檔案，並新增 android.useDeprecatedNdk=true。

更新 Gradle 建構指令碼

  • 開啟 build.gradle (Module:app) 檔案，並按照下列指南更新設定，以符合 Navigation SDK 的需求，並考慮設定最佳化選項。

    Navigation SDK 的必要設定

    1. 將 minSdkVersion 設為 23 以上。
    2. 將 targetSdkVersion 設為 33 以上。
    3. 新增會增加 javaMaxHeapSize 的 dexOptions 設定。
    4. 設定其他程式庫的位置。
    5. 為 Navigation SDK 新增 repositories 和 dependencies。
    6. 請將依附元件中的版本號碼替換成最新可用版本。

    可縮短建構時間的選用設定

    • 使用 R8/ProGuard 啟用程式碼縮減和資源縮減功能，從依附元件中移除未使用的程式碼和資源。如果 R8/ProGuard 步驟執行時間過長，請考慮為開發工作啟用 Multidex。
    • 減少建構作業中包含的語言翻譯數量：在開發期間為一種語言設定 resConfigs。在最終版本中，請針對您實際使用的語言設定 resConfigs。根據預設，Gradle 會針對 Navigation SDK 支援的所有語言提供資源字串。

    新增 Java8 支援的脫糖功能

    • 如果您使用 Android Gradle 外掛程式 4.0.0 以上版本建構應用程式，這個外掛程式會擴充支援使用多種 Java 8 語言 API。詳情請參閱 Java 8 脫糖支援一文。請參閱下方建構指令碼範例，瞭解編譯和依附元件選項的方式。

以下是應用程式的 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 33
        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:1.1.9'
}

在應用程式中加入 API 金鑰

本節將說明如何儲存 API 金鑰，讓應用程式以安全的方式參照金鑰。API 金鑰不應該登錄在版本管控系統中；我們建議將金鑰儲存在位於專案根目錄的 secrets.properties 檔案內。如要進一步瞭解 secrets.properties 檔案，請參閱這篇文章中關於 Gradle 屬性檔案的說明。

建議您使用 Secrets Gradle Plugin for Android 來簡化這項工作。

如要在 Google 地圖專案中安裝 Secrets Gradle Plugin for Android，請按照下列步驟操作：

  1. 在 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")
    }
}
  2. 開啟模組層級的 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")
}
  3. 在模組層級的 build.gradle 檔案中，確認 targetSdk 和 compileSdk 已設為 34。
  4. 儲存檔案，然後使用 Gradle 同步處理專案。
  5. 開啟頂層目錄中的 secrets.properties 檔案，並加入下列程式碼，然後將 YOUR_API_KEY 替換成您的 API 金鑰。secrets.properties 不會登錄在版本管控系統中，因此請將金鑰儲存至該檔案。 
    MAPS_API_KEY=YOUR_API_KEY
  6. 儲存檔案。

  7. 在頂層目錄 (與 secrets.properties 檔案相同的資料夾) 中建立 local.defaults.properties 檔案，然後加入下列程式碼。

    MAPS_API_KEY=DEFAULT_API_KEY

    如果找不到 secrets.properties 檔案，這個檔案便可做為 API 金鑰的備份位置，以確保建置程序不會失敗。如果您從略過 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 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.*"
}

在應用程式中加入必要的作者資訊

如果您在應用程式中使用 Android 版 Navigation SDK，請務必在應用程式的法律聲明部分中加入作者資訊文字和開放原始碼授權。

您可以在 Navigation SDK for Android ZIP 檔案中找到必要的歸因文字和開放原始碼授權：

  • NOTICE.txt
  • LICENSES.txt

如果您是 Mobility 或 Fleet Engine Deliveries 客戶

如果您是 Mobility 或 Fleet Engine Deliveries 客戶，請參閱 Mobility 說明文件中的計費方式。如要進一步瞭解如何記錄交易，請參閱「設定帳單資訊」、「記錄可計費交易」、「報表」和「記錄可計費交易 (Android)」。