Trang này mô tả cách định cấu hình dự án Android Studio để sử dụng Maps SDK dành cho Android mà không cần sử dụng mẫu Google Maps được nêu chi tiết trong phần Bắt đầu nhanh.
Mẫu Google Maps tự động định cấu hình và thêm bản đồ cơ bản vào dự án Android Studio mới. Tuy nhiên, bạn cũng có thể thêm bản đồ vào một dự án Android sử dụng mẫu Android Studio khác. Để thực hiện việc này, bạn cần định cấu hình dự án theo cách thủ công rồi thêm bản đồ.
Bước 1: Thiết lập Android Studio
Tài liệu này mô tả môi trường phát triển sử dụng Android Studio Hedgehog và trình bổ trợ Android cho Gradle phiên bản 8.2.
Bước 2. Thiết lập SDK
Thư viện SDK Maps dành cho Android có sẵn thông qua Kho lưu trữ Maven của Google. Để thêm SDK vào ứng dụng, hãy làm như sau:
- Trong tệp
settings.gradle
cấp cao nhất, hãy đưa cổng thông tin trình bổ trợ Gradle, Kho lưu trữ Google Maven và Kho lưu trữ trung tâm Maven vào khốipluginManagement
. KhốipluginManagement
phải xuất hiện trước mọi câu lệnh khác trong tập lệnh.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- Trong tệp
settings.gradle
cấp cao nhất, hãy đưa Kho lưu trữ Maven của Google và Kho lưu trữ trung tâm Maven vào khốidependencyResolutionManagement
:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- Trong tệp
build.gradle
ở cấp mô-đun, hãy thêm phần phụ thuộc Dịch vụ Google Play cho SDK Maps dành cho Android.Groovy
dependencies { // Maps SDK for Android implementation 'com.google.android.gms:play-services-maps:19.0.0' }
Kotlin
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:18.2.0") }
- Trong tệp
build.gradle
ở cấp mô-đun, hãy đặtcompileSdk
vàminSdk
thành các giá trị sau:Groovy
android { compileSdk 34 defaultConfig { minSdk 21 // ... } }
Kotlin
android { compileSdk = 34 defaultConfig { minSdk = 21 // ... } }
- Trong phần
buildFeatures
của tệpbuild.gradle
cấp mô-đun, hãy thêm lớpBuildConfig
mà bạn có thể dùng để truy cập vào các giá trị siêu dữ liệu được xác định sau trong quy trình này:Groovy
android { // ... buildFeatures { buildConfig true // ... } }
Kotlin
android { // ... buildFeatures { buildConfig = true // ... } }
Bước 3: Thêm khoá API vào dự án
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
hoặcbuild.gradle.kts
ở cấp cao nhất rồi thêm mã sau vào phần tửdependencies
trongbuildscript
.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") } }
-
Mở tệp
build.gradle
ở cấp mô-đun và thêm mã sau vào phần tửplugins
.Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
Kotlin
plugins { id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
- Trong tệp
build.gradle
ở cấp mô-đun, hãy đảm bảo rằngtargetSdk
vàcompileSdk
được đặt thành 34. - Lưu tệp và đồng bộ hoá dự án của bạ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. Lưu trữ khoá của bạn trong tệp này vìsecrets.properties
sẽ không được kiểm tra trong một hệ thống quản lý phiên bản.MAPS_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.MAPS_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}" />
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 Maps SDK for Android. For backwards compatibility, the API also supports the namecom.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. -
In Android Studio, open your module-level
build.gradle
orbuild.gradle.kts
file and edit thesecrets
property. If thesecrets
property does not exist, add it.Edit the properties of the plugin to set
propertiesFileName
tosecrets.properties
, setdefaultPropertiesFileName
tolocal.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.*" }
Bước 4: Cập nhật tệp kê khai ứng dụng
Phần này mô tả các chế độ cài đặt cần thêm vào tệp
AndroidManifest.xml
.Số phiên bản của Dịch vụ Google Play
Thêm nội dung khai báo sau đây trong phần tử
application
. Thao tác này sẽ nhúng phiên bản Dịch vụ Google Play mà ứng dụng được biên dịch.<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />
Quyền truy cập thông tin vị trí
Nếu ứng dụng của bạn cần truy cập vào thông tin vị trí của người dùng, bạn cần yêu cầu quyền truy cập thông tin vị trí trong tệp
AndroidManifest.xml
. Các tuỳ chọn làACCESS_FINE_LOCATION
cung cấp vị trí chính xác của thiết bị vàACCESS_COARSE_LOCATION
(có độ chính xác thấp hơn). Để biết thông tin chi tiết, vui lòng xem hướng dẫn về dữ liệu vị trí.Để yêu cầu quyền
ACCESS_FINE_LOCATION
, hãy thêm mã này vào phần tửmanifest
:<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
Quyền truy cập vào bộ nhớ ngoài
Nếu đang nhắm đến phiên bản 8.3 trở lên của SDK Dịch vụ Google Play, thì bạn không cần quyền
WRITE_EXTERNAL_STORAGE
. Nếu đang nhắm đến các phiên bản cũ của SDK Dịch vụ Google Play, thì bạn phải yêu cầu quyền WRITE_EXTERNAL_STORAGE trong phần tửmanifest
.<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
Thư viện Apache HTTP cũ
Nếu đang sử dụng
com.google.android.gms:play-services-maps:16.0.0
trở xuống và ứng dụng của bạn đang nhắm đến API cấp 28 (Android 9.0) trở lên, bạn phải đưa nội dung khai báo sau vào phần tử<application>
củaAndroidManifest.xml
. Nếu không, hãy bỏ qua phần khai báo này.<uses-library android:name="org.apache.http.legacy" android:required="false" />
Bước 5: Thiết lập thiết bị Android
Để chạy một ứng dụng sử dụng SDK Maps dành cho Android, bạn phải triển khai ứng dụng đó trên thiết bị Android hoặc trình mô phỏng Android dựa trên Android 5.0 trở lên và bao gồm các API của Google.
- Để sử dụng thiết bị Android, hãy làm theo hướng dẫn trong bài viết Chạy ứng dụng trên thiết bị phần cứng.
- Để sử dụng trình mô phỏng Android, bạn có thể tạo một thiết bị ảo và cài đặt trình mô phỏng bằng cách sử dụng Trình quản lý thiết bị Android ảo (AVD) đi kèm với Android Studio.
Bước 6: Kiểm tra xem có hỗ trợ Dịch vụ Play không (không bắt buộc)
SDK bản đồ dành cho Android yêu cầu thiết bị mà bạn triển khai ứng dụng phải cài đặt Dịch vụ Google Play trên đó. Google cung cấp một phương thức mà bạn có thể gọi từ ứng dụng của mình để kiểm tra. Để biết thêm thông tin, hãy xem phần Kiểm tra xem Dịch vụ Google Play đã được cài đặt chưa.
Các bước tiếp theo
Sau khi dự án của bạn được định cấu hình, bạn có thể thêm bản đồ.
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2024-07-13 UTC.
[] []