Navigation SDK 目前僅供特定客戶使用。如要瞭解詳情，請聯絡銷售人員。

Google 地圖平台即將推出全新地圖樣式設定。本次地圖樣式更新包含新的預設調色盤，並改善地圖體驗和可用性。所有地圖樣式都將在 2025 年 3 月自動更新。如要進一步瞭解可用性及如何選擇加入計畫，請參閱「Google 地圖平台的全新地圖樣式」一文。

本頁面由 Cloud Translation API 翻譯而成。

設定 Android Studio 專案

本頁面說明如何將 Navigation SDK 整合至開發專案。

在專案中新增 Navigation SDK

您可以透過 Google Maven 存放區取得 Navigation SDK。您可以使用 Gradle build.gradle 或 Maven pom.xml 設定將 SDK 新增至專案。

將下列依附元件新增至 Gradle 或 Maven 設定，並將 VERSION_NUMBER 預留位置替換為所需的 Navigation SDK for Android 版本。

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>
```
注意： 如果您是行動服務客戶，且從原始私人 Maven 存放區升級，請注意群組和構件名稱已有所變更，因此不再需要使用 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 屬性

在「Gradle Scripts」資料夾中，開啟 gradle.properties 檔案，然後新增下列內容 (如果尚未存在)：
1. android.useAndroidX=true
2. android.enableJetifier=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 進行開發工作。
- 減少版本中包含的語言翻譯數量：在開發期間為一種語言設定 resConfigs。針對最終版本，請為實際使用的語言設定 resConfigs。根據預設，Gradle 包含 Navigation SDK 支援所有語言的資源字串。
新增對 Java8 支援的脫糖功能
- 如果您使用 Android Gradle 外掛程式 4.0.0 以上版本建構應用程式，這個外掛程式會擴大支援使用多種 Java 8 語言 API。詳情請參閱「Java 8 去糖化支援」。請參閱下方的建構指令碼片段範例，瞭解如何使用編譯和依附元件選項。
- 建議使用 Gradle 8.4、Android Gradle 外掛程式 8.3.0 版，以及 Desugar 程式庫 com.android.tools:desugar_jdk_libs_nio:2.0.3。這項設定與 Android 適用的 Navigation SDK 6.0.0 以上版本相容。
- 您必須為 app 模組和直接依附 Navigation SDK 的模組啟用 Desugar 程式庫。

以下提供應用程式的 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 屬性檔案的說明。

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

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

在 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
```
如果找不到 secrets.properties 檔案，這個檔案便可做為 API 金鑰的備份位置，以確保建置程序不會失敗。如果您從略過 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 第 2 版進行驗證。應用程式只能指定這兩種 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.*"
}

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

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

您可以在 Android 適用的 Navigation SDK .zip 檔案中找到必要的歸屬文字和開放原始碼授權：

NOTICE.txt
LICENSES.txt

如果您是 Mobility 或 Fleet Engine Delivery 客戶

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