本指南列出了使用 Navigation SDK for Android。下文的操作說明假設您使用 Android IDE 已安裝,且熟悉 Android 開發作業。
使用 Navigation SDK 的基本需求
這些規定適用於 Android 4.99 以下版本的 Navigation SDK。
已啟用 Navigation SDK 的 Google Cloud 控制台專案。 如需佈建,請洽詢 Google 地圖平台代表。
應用程式必須指定 API 級別 30 以上版本。
如要執行使用 Navigation SDK 建構的應用程式,Android 裝置必須安裝 Google Play 服務 安裝並啟用
設定專案:Cloud 控制台專案和 Android 專案
您必須先建立 Cloud 控制台專案,才能建立或測試應用程式 並新增 API 金鑰憑證專案必須設有佈建,才能存取 Navigation SDK。Cloud 控制台專案中的所有金鑰 所授予的權限與 Navigation SDK 相同。一把鑰匙 可能會有多個相關聯的開發專案。如果您已有控制台專案,就可以將金鑰新增至目前的專案。
如何設定
- 在您慣用的網路瀏覽器中登入 Cloud 控制台,並建立 Cloud 控制台 專案。
- 在 IDE (例如 Android Studio) 中,建立 Android 應用程式開發作業 並記下套件名稱
- 請聯絡 Google 地圖平台代表,以取得 Cloud 控制台專用的 Navigation SDK 專案。
- 在網路瀏覽器中前往 Cloud 控制台資訊主頁時, 建立憑證以產生設有限制的 API 金鑰。
- 在「API 金鑰」頁面的「應用程式限制」中,按一下「Android 應用程式」
- 按一下「Add the package name and fingerprint」(新增套件名稱和指紋),然後輸入套件 和該金鑰的 SHA-1 指紋。
- 按一下 [儲存]。
在專案中新增 Navigation SDK
可透過 Maven 取得 Navigation SDK,或 AAR 套裝組合: 建立開發專案後,您可以透過下列方式將 SDK 整合至專案: 選擇使用下列任一種方法
使用 Maven 安裝 Navigation SDK 4.5 以上版本 (建議)
以下使用最簡單的 google()
Maven 存放區
將 Navigation SDK 加入
專案
將以下依附元件新增至 Gradle 或 Maven 設定。 將
VERSION_NUMBER
預留位置替換成 所需的導覽 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>
使用 4.5 以下版本的 Navigation SDK 或搭配驅動程式 SDK
Navigation SDK 會繼續透過
原始 Maven 存放區這是
具備與上述版本相同的所有更新
與驅動程式 SDK 和其他程式庫相容。使用
這項依附元件需要透過 gcloud
登入雲端專案,
進行訓練
- 按照 事前準備 一節。可以使用 Navigation SDK 是透過工作區群組控制。
將以下依附元件新增至 Gradle 或 Maven 設定,將 所需 Navigation SDK 版本的
VERSION_NUMBER
預留位置。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。這些操作說明 假設您的 IDE 使用 Android Studio。
下載最新版 Navigation SDK 共用的 Google 雲端硬碟檔案,然後解壓縮。如果發生以下情況: 沒有存取權,請與您的代表聯絡。
在 Android Studio 中開啟專案,然後 新增 Google Play 服務套件 使用 SDK Manager。
將 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.gradle (Module:app)
檔案,並依照下列規範 請更新設定,以符合 Navigation SDK 的需求 並考慮同時設定最佳化選項Navigation SDK 的必要設定
- 將
minSdkVersion
設為 23 以上。 - 將
targetSdkVersion
設為 30 以上。 - 新增會調高
javaMaxHeapSize
的dexOptions
設定。 - 設定其他程式庫的位置。
- 為 Navigation SDK 新增
repositories
和dependencies
。 - 將依附元件中的版本號碼替換為最新可用版本。
縮短建構時間的選用設定
- 啟用 程式碼縮減和資源縮減 使用 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. 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 屬性檔案的說明。
建議您使用 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
不會登錄在版本管控系統中,因此請將金鑰儲存至該檔案。NAV_API_KEY=YOUR_API_KEY
- 儲存檔案。
-
在頂層目錄 (與
secrets.properties
檔案相同的資料夾) 中建立local.defaults.properties
檔案,然後加入下列程式碼。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,包括 Navigation SDK for Android。為了兼顧回溯相容性,API 也會 支援名稱com.google.android.maps.v2.API_KEY
。這個舊版 名稱僅允許對 Android Maps API 第 2 版進行驗證。應用程式可以 您只能指定其中一個 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,則必須在 將作者資訊文字和開放原始碼授權納入應用程式的法律聲明中 專區。
如需必要的作者資訊文字和開放原始碼授權,請前往「 Navigation SDK for Android ZIP 檔案:
NOTICE.txt
LICENSES.txt