設定專案 -- 4.99 以下版本

本指南列出使用 Navigation SDK for Android 的建構設定規定。操作說明假設您已安裝 Android IDE,且熟悉 Android 開發作業。

使用 Navigation SDK 的最低需求

這些規定適用於 Navigation SDK for Android 4.99 以下版本。

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

建構或測試應用程式前,您需要建立 Cloud 控制台專案,並新增 API 金鑰憑證。專案必須具備 Navigation SDK 存取權。Cloud 控制台專案中的所有金鑰,都具備相同的 Navigation SDK 存取權。一個金鑰可以與多個開發專案建立關聯。如果您已有控制台專案,可以將金鑰新增至目前的專案。

設定方式

  1. 在您偏好的網路瀏覽器中登入 Cloud 控制台,並建立 Cloud 控制台專案。
  2. 在 Android Studio 等 IDE 中,建立 Android 應用程式開發專案,並記下套件名稱。
  3. 請與 Google Maps Platform 代表聯絡,為 Cloud 控制台專案提供 Navigation SDK 存取權。
  4. 在網路瀏覽器中開啟 Cloud 控制台資訊主頁,建立憑證來產生設有限制的 API 金鑰。
  5. 在「API 金鑰」頁面的「應用程式限制」區域,點選「Android 應用程式」。
  6. 按一下「Add the package name and fingerprint」(新增套件名稱和指紋),然後輸入開發專案的套件名稱和該金鑰的 SHA-1 指紋。
  7. 按一下 [儲存]。

在專案中加入 Navigation SDK

您可以透過 Maven 或 AAR 軟體包取得 Navigation SDK。建立開發專案後,您可以採用下列其中一種方法,將 SDK 整合至專案。

使用 Maven 取得 Navigation SDK 4.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 使用

在第 4 版的其餘版本中,Navigation SDK 仍可透過原始 Maven 存放區取得。這個程式庫與上述版本相同,且包含所有相同的更新,並在轉換期間提供與 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 Manager 新增 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.gradle (Module:app) 檔案,並按照下列指南更新設定,以符合 Navigation SDK 的需求,同時考慮設定最佳化選項。

    Navigation SDK 的必要設定

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

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

    • 使用 R8/ProGuard 啟用程式碼縮減和資源縮減功能,從依附元件中移除未使用的程式碼和資源。如果 R8/ProGuard 步驟需要太長時間才能執行,請考慮為開發工作啟用 multidex。
    • 減少建構作業中包含的語言翻譯數量:在開發期間,為一種語言設定 resConfigs。在最終版本中,請為實際使用的語言設定 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 屬性檔案,請參閱這篇文章。

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

如要安裝 Secrets Gradle Plugin for Android 並儲存 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

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

      注意:API 金鑰的建議中繼資料名稱為 com.google.android.geo.API_KEY。具備這個名稱的金鑰可用來驗證 Android 平台上的多個 Google 地圖相關 API,包括 Navigation SDK for Android。為了兼顧回溯相容性,API 也支援 com.google.android.maps.v2.API_KEY 這個名稱。此舊版名稱僅允許對 Android Maps API 第 2 版進行驗證。應用程式只能指定這兩種 API 金鑰中繼資料名稱的其中一個;如果同時指定兩者,API 會擲回例外狀況。

    • 透過程式輔助方式提供 API 金鑰:

      Secrets Gradle 外掛程式會在 BuildConfig 類別中提供金鑰。在應用程式初始化期間 (例如在 Application.onCreate() 方法中),呼叫以下方法:

      Kotlin

      1. 新增下列匯入陳述式:
        import com.google.android.libraries.navigation.NavigationApi
      2. 在 Application.onCreate() 方法中加入以下內容:
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

      Java

      1. 新增下列匯入陳述式:
        import com.google.android.libraries.navigation.NavigationApi;
      2. 在 Application.onCreate() 方法中加入以下內容:
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
      注意:使用 setApiKey() 時,請注意下列事項:
      • 請提供非空值、非空白的 API 金鑰。
      • 在應用程式生命週期內,請只呼叫 setApiKey() 一次。如果多次呼叫,這個方法會擲回 IllegalStateException。
      • 請先呼叫 setApiKey(),再初始化其他 Navigation SDK 元件,例如 Navigator。
      • 您透過這個方法提供的金鑰,會覆寫 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