Hướng dẫn này liệt kê các yêu cầu về cấu hình bản dựng để sử dụng SDK điều hướng cho Android. Các hướng dẫn này giả định rằng bạn đã cài đặt IDE Android và quen với việc phát triển Android.
Các yêu cầu tối thiểu để sử dụng SDK điều hướng
Những yêu cầu này áp dụng cho SDK điều hướng dành cho Android phiên bản 4.99 trở xuống.
Một dự án Google Cloud Console có bật SDK điều hướng. Để cung cấp, hãy hỏi người đại diện Nền tảng Google Maps của bạn.
Ứng dụng của bạn phải nhắm đến API cấp 30 trở lên.
Để chạy một ứng dụng được tạo bằng SDK điều hướng, bạn phải cài đặt và bật Dịch vụ Google Play trên thiết bị Android.
Thuộc tính và văn bản cấp phép phải được thêm vào ứng dụng.
Thiết lập dự án: Dự án Cloud Console và dự án Android
Trước khi có thể tạo hoặc kiểm thử một ứng dụng, bạn cần tạo một dự án trên Cloud Console và thêm thông tin xác thực khoá API. Dự án phải có quyền cấp phép để truy cập vào SDK Điều hướng. Tất cả các khoá trong dự án Cloud Console đều được cấp cùng quyền truy cập vào SDK điều hướng. Một khoá có thể liên kết với nhiều dự án phát triển. Nếu đã có dự án trên bảng điều khiển, bạn có thể thêm khoá vào dự án hiện tại.
Cách thiết lập
- Trong trình duyệt web mà bạn yêu thích, hãy đăng nhập vào Cloud Console rồi tạo dự án Cloud Console.
- Trong IDE của bạn, chẳng hạn như Android Studio, hãy tạo một dự án phát triển ứng dụng Android và ghi lại tên gói.
- Hãy liên hệ với người đại diện của Nền tảng Google Maps để cấp quyền truy cập vào SDK Điều hướng cho dự án trên Cloud Console.
- Trên trang tổng quan của Cloud Console trong trình duyệt web, hãy tạo thông tin xác thực để tạo khoá API có các quy định hạn chế.
- Trên trang khoá API, hãy nhấp vào Ứng dụng Android trong khu vực Hạn chế cho ứng dụng.
- Nhấp vào Thêm tên gói và vân tay số, sau đó nhập tên gói của dự án phát triển và vân tay số SHA-1 cho khoá đó.
- Nhấp vào Lưu.
Thêm Navigation SDK vào dự án
Bạn có thể sử dụng SDK Điều hướng thông qua Maven hoặc dưới dạng gói AAR. Sau khi tạo dự án phát triển, bạn có thể tích hợp SDK vào dự án đó bằng một trong các phương pháp sau.
Sử dụng Maven cho SDK điều hướng phiên bản 4.5 trở lên (nên dùng)
Phần sau đây sử dụng kho lưu trữ Maven google()
. Đây là cách đơn giản nhất và nên dùng để thêm SDK điều hướng vào dự án của bạn
Thêm phần phụ thuộc sau vào cấu hình Gradle hoặc Maven, thay thế phần giữ chỗ
VERSION_NUMBER
cho phiên bản mong muốn của SDK điều hướng cho Android.Gradle
Thêm nội dung sau vào
build.gradle
cấp mô-đun:dependencies { ... implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER' }
Nếu nâng cấp từ kho lưu trữ Maven ban đầu, hãy lưu ý rằng tên nhóm và cấu phần phần mềm đã thay đổi, đồng thời trình bổ trợ
com.google.cloud.artifactregistry.gradle-plugin
không còn cần thiết nữa.Và thêm đoạn mã sau vào
build.gradle
cấp cao nhất: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
Thêm nội dung sau vào
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.libraries.navigation</groupId> <artifactId>navigation</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
Nếu có bất kỳ phần phụ thuộc nào sử dụng SDK Maps, thì bạn phải loại trừ phần phụ thuộc đó trong từng phần phụ thuộc đã khai báo dựa trên SDK Maps.
<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>
Sử dụng Maven cho SDK Điều hướng trước phiên bản 4.5 hoặc với SDK Trình điều khiển
Navigation SDK vẫn được cung cấp thông qua kho lưu trữ Maven ban đầu trong các phiên bản v4 còn lại. Đây là thư viện giống với tất cả các bản cập nhật giống như phiên bản ở trên và cung cấp khả năng tương thích với SDK Trình điều khiển và các thư viện khác trong quá trình chuyển đổi. Để sử dụng phần phụ thuộc này, bạn cần đăng nhập vào dự án trên đám mây thông qua gcloud
khi biên dịch.
- Thiết lập môi trường để truy cập vào kho lưu trữ Maven của Google như mô tả trong phần Điều kiện tiên quyết của tài liệu về SDK dành cho người dùng. Quyền truy cập vào SDK điều hướng được kiểm soát thông qua một nhóm không gian làm việc.
Thêm phần phụ thuộc sau vào cấu hình Gradle hoặc Maven, thay thế phần giữ chỗ
VERSION_NUMBER
cho phiên bản Navigation SDK mong muốn.Gradle
Thêm đoạn mã sau vào
build.gradle
cấp mô-đun:dependencies { ... implementation 'com.google.android.maps:navsdk:VERSION_NUMBER' }
Và thêm đoạn mã sau vào
build.gradle
cấp cao nhất: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
Thêm nội dung sau vào
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.maps</groupId> <artifactId>navsdk</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
Nếu có bất kỳ phần phụ thuộc nào sử dụng SDK Maps, thì bạn phải loại trừ phần phụ thuộc đó trong từng phần phụ thuộc đã khai báo dựa trên SDK Maps.
<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>
Sử dụng gói AAR đã tải xuống (không nên dùng)
SDK Điều hướng cũng có sẵn dưới dạng gói AAR. Sau khi tạo dự án phát triển, bạn có thể tích hợp SDK. Những hướng dẫn này giả định việc sử dụng Android Studio cho IDE của bạn.
Tải phiên bản mới nhất của SDK điều hướng xuống từ Google Drive dùng chung và giải nén phiên bản đó. Nếu bạn không có quyền truy cập, hãy liên hệ với người đại diện của mình.
Trong Android Studio, hãy mở một dự án và thêm gói Dịch vụ Google Play bằng Trình quản lý SDK.
Từ thư mục tệp zip, hãy sao chép
libs/google_navigation_navmap.aar
vào thư mụcapp/libs
của dự án.Thêm nội dung sau vào
build.gradle
cấp mô-đun:implementation(name: 'google_navigation_navmap', ext: 'aar')
Và thêm nội dung sau vào
build.gradle
cấp cao nhất: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' } } }
Định cấu hình bản dựng
Sau khi tạo dự án, bạn có thể định cấu hình các chế độ cài đặt để tạo bản dựng và sử dụng thành công SDK Điều hướng.
Cập nhật thuộc tính cục bộ
- Trong thư mục Gradle Scripts (Tập lệnh Gradle), hãy mở tệp
local.properties
rồi thêmandroid.useDeprecatedNdk=true
.
Cập nhật tập lệnh bản dựng Gradle
Mở tệp
build.gradle (Module:app)
và sử dụng các nguyên tắc sau để cập nhật chế độ cài đặt nhằm đáp ứng các yêu cầu đối với SDK Điều hướng và cân nhắc việc thiết lập các tuỳ chọn tối ưu hoá.Các chế độ cài đặt bắt buộc cho SDK điều hướng
- Đặt
minSdkVersion
thành 23 trở lên. - Đặt
targetSdkVersion
thành 30 trở lên. - Thêm một chế độ cài đặt
dexOptions
để tăngjavaMaxHeapSize
. - Đặt vị trí cho các thư viện bổ sung.
- Thêm
repositories
vàdependencies
cho SDK điều hướng. - Thay thế số phiên bản trong các phần phụ thuộc bằng các phiên bản mới nhất hiện có.
Các chế độ cài đặt không bắt buộc để giảm thời gian xây dựng
- Bật tính năng rút gọn mã và rút gọn tài nguyên bằng cách sử dụng R8/ProGuard để xoá mã và tài nguyên không dùng đến khỏi các phần phụ thuộc. Nếu bước R8/ProGuard mất quá nhiều thời gian để chạy, hãy cân nhắc bật tính năng multidex cho công việc phát triển.
- Giảm số lượng bản dịch ngôn ngữ có trong bản dựng: Đặt
resConfigs
cho một ngôn ngữ trong quá trình phát triển. Đối với bản dựng hoàn chỉnh, hãy đặtresConfigs
cho các ngôn ngữ bạn thực sự sử dụng. Theo mặc định, Gradle bao gồm các chuỗi tài nguyên cho tất cả ngôn ngữ mà Navigation SDK hỗ trợ.
- Đặt
Dưới đây là ví dụ về tập lệnh bản dựng Gradle cho ứng dụng. Kiểm tra ứng dụng mẫu để biết các nhóm phần phụ thuộc mới cập nhật, vì phiên bản SDK điều hướng mà bạn đang sử dụng có thể ở phía trước hoặc phía sau tài liệu này một chút.
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'
}
Thêm khoá API vào ứng dụng
Phần này mô tả cách lưu trữ khoá API để ứng dụng của bạn có thể tham chiếu một cách an toàn. Bạn không nên kiểm tra khoá API trong hệ thống quản lý phiên bản. Vì vậy, bạn nên lưu trữ khoá đó trong tệp secrets.properties
, nằm trong thư mục gốc của dự án. Để biết thêm thông tin về tệp secrets.properties
, hãy xem các tệp thuộc tính Gradle.
Để đơn giản hoá tác vụ này, bạn nên sử dụng Trình bổ trợ Secrets Gradle cho Android.
Cách cài đặt Trình bổ trợ Secrets Gradle cho Android trong dự án Google Maps:
-
Trong Android Studio, hãy mở tệp
build.gradle.kts
hoặcbuild.gradle
cấp cao nhất và thêm mã sau vào phần tửdependencies
trongbuildscript
.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" } }
-
Mở tệp
build.gradle.kts
hoặcbuild.gradle
ở cấp mô-đun và thêm đoạn mã sau vào phần tửplugins
.Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- Trong tệp
build.gradle.kts
hoặcbuild.gradle
ở cấp mô-đun, hãy đảm bảo rằng bạn đặttargetSdk
vàcompileSdk
thành 34. - Lưu tệp và đồng bộ hoá dự án với Gradle.
-
Mở tệp
secrets.properties
trong thư mục cấp cao nhất của bạn, sau đó thêm mã sau. Thay thếYOUR_API_KEY
bằng khoá API của bạn. Lưu trữ khoá của bạn trong tệp này vìsecrets.properties
không được đưa vào hệ thống quản lý phiên bản.NAV_API_KEY=YOUR_API_KEY
- Lưu tệp.
-
Tạo tệp
local.defaults.properties
trong thư mục cấp cao nhất, cùng thư mục với tệpsecrets.properties
, sau đó thêm mã sau.NAV_API_KEY=DEFAULT_API_KEY
Mục đích của tệp này là cung cấp vị trí sao lưu cho khoá API nếu hệ thống không tìm thấy tệp
secrets.properties
để các bản dựng sẽ không bị lỗi. Điều này có thể xảy ra nếu bạn sao chép ứng dụng từ một hệ thống quản lý phiên bản bỏ quasecrets.properties
và bạn chưa tạo tệpsecrets.properties
cục bộ để cung cấp khoá API. - Lưu tệp.
-
Trong tệp
AndroidManifest.xml
, hãy chuyển đếncom.google.android.geo.API_KEY
rồi cập nhậtandroid:value attribute
. Nếu thẻ<meta-data>
chưa tồn tại, hãy tạo thẻ đó làm thẻ con của thẻ<application>
.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
Lưu ý:
com.google.android.geo.API_KEY
là tên siêu dữ liệu nên dùng cho khoá API. Bạn có thể dùng khoá có tên này để xác thực nhiều API dựa trên Google Maps trên nền tảng Android, bao gồm cả SDK điều hướng dành cho Android. Để tương thích ngược, API cũng hỗ trợ têncom.google.android.maps.v2.API_KEY
. Tên cũ này chỉ cho phép xác thực API Android Maps phiên bản 2. Một ứng dụng chỉ có thể chỉ định một trong các tên siêu dữ liệu khoá API. Nếu bạn chỉ định cả hai, thì API sẽ gửi một trường hợp ngoại lệ. -
Trong Android Studio, hãy mở tệp
build.gradle.kts
hoặcbuild.gradle
ở cấp mô-đun rồi chỉnh sửa thuộc tínhsecrets
. Nếu thuộc tínhsecrets
không tồn tại, hãy thêm thuộc tính đó.Chỉnh sửa các thuộc tính của trình bổ trợ để đặt
propertiesFileName
thànhsecrets.properties
, đặtdefaultPropertiesFileName
thànhlocal.defaults.properties
và đặt bất kỳ thuộc tính nào khác.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.*" }
Đưa các thuộc tính bắt buộc vào ứng dụng của bạn
Nếu sử dụng SDK điều hướng dành cho Android trong ứng dụng của mình, thì bạn phải đưa văn bản phân bổ và giấy phép nguồn mở vào mục thông báo pháp lý của ứng dụng.
Bạn có thể tìm thấy văn bản ghi nhận tác giả và giấy phép nguồn mở cần thiết trong SDK điều hướng dành cho tệp zip của Android:
NOTICE.txt
LICENSES.txt