Trang này được dịch bởi Cloud Translation API.

Hướng dẫn nhanh về SDK Bản đồ dành cho Android

Tạo một ứng dụng Android hiển thị bản đồ bằng cách sử dụng mẫu Google Maps Views cho Android Studio. Nếu bạn có một dự án Android Studio hiện tại mà bạn muốn thiết lập, hãy xem phần Thiết lập dự án Android Studio.

Hướng dẫn nhanh này dành cho những nhà phát triển đã quen thuộc với hoạt động phát triển Android cơ bản bằng Kotlin hoặc Java.

Giới thiệu về môi trường phát triển

Hướng dẫn nhanh này được phát triển bằng Android Studio Hedgehog và trình bổ trợ Android cho Gradle phiên bản 8.2.

Thiết lập thiết bị Android

Để chạy một ứng dụng sử dụng Maps SDK cho Android, bạn phải triển khai ứng dụng đó trên một thiết bị Android hoặc trình mô phỏng Android dựa trên Android 5.0 trở lên và có các API của Google.

Để sử dụng thiết bị Android, hãy làm theo hướng dẫn trong phần 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ị ảo Android (AVD) đi kèm với Android Studio.
Lưu ý: Nếu bạn chọn sử dụng trình mô phỏng Android, hãy đảm bảo rằng bạn chọn một thiết bị có biểu tượng Play, , xuất hiện trong cột Cửa hàng Play. Biểu tượng này cho biết các hồ sơ này hoàn toàn tuân thủ CTS và có thể sử dụng hình ảnh hệ thống có chứa ứng dụng Cửa hàng Play:

Tạo một dự án Google Maps trong Android Studio

Quy trình tạo dự án Google Maps trong Android Studio đã thay đổi trong Flamingo và các bản phát hành sau này của Android Studio.

Mở Android Studio rồi nhấp vào New Project (Dự án mới) trong cửa sổ Welcome to Android Studio (Chào mừng bạn đến với Android Studio).
Trong cửa sổ New Project (Dự án mới), trong danh mục Phone and Tablet (Điện thoại và máy tính bảng), hãy chọn No Activity (Không có hoạt động) rồi nhấp vào Next (Tiếp theo).
Hoàn tất biểu mẫu Dự án mới:
- Đặt Language (Ngôn ngữ) thành Java hoặc Kotlin. SDK Maps dành cho Android hỗ trợ đầy đủ cả hai ngôn ngữ này. Để tìm hiểu thêm về Kotlin, hãy xem phần Phát triển ứng dụng Android bằng Kotlin.
- Đặt SDK tối thiểu thành phiên bản SDK tương thích với thiết bị thử nghiệm của bạn. Bạn phải chọn một phiên bản lớn hơn phiên bản tối thiểu mà Maps SDK for Android phiên bản 19.0.x yêu cầu, đó là Android API cấp 21 ("Lollipop"; Android 5.0) trở lên. Hãy xem Ghi chú phát hành để biết thông tin mới nhất về các yêu cầu đối với phiên bản SDK.
  
  Lưu ý: Nếu bạn không chắc nên chọn phiên bản SDK nào, hãy chọn đường liên kết Giúp tôi chọn để hiển thị thông tin phân phối cho các SDK Android được hỗ trợ. Ví dụ: nếu bạn chọn Android API cấp 21 ("Lollipop"; Android 5.0), thì ứng dụng của bạn sẽ chạy trên hơn 99% thiết bị Android.
- Đặt Ngôn ngữ cấu hình bản dựng thành Kotlin DSL hoặc Groovy DSL. Đoạn mã cho cả hai ngôn ngữ cấu hình bản dựng sẽ xuất hiện trong các quy trình sau.
Nhấp vào Hoàn tất.

Android Studio sẽ khởi động Gradle và tạo dự án. Quá trình này có thể mất chút thời gian.
Thêm Hoạt động trên Google Maps Views:
1. Nhấp chuột phải vào thư mục app trong dự án của bạn.
2. Chọn New > Google > Google Maps Views Activity (Mới > Google > Hoạt động của thành phần hiển thị Google Maps).
3. Trong hộp thoại New Android Activity (Hoạt động mới trên Android), hãy đánh dấu vào hộp Launcher Activity (Hoạt động của trình chạy).
4. Chọn Hoàn tất.
  
  Để biết thêm thông tin, hãy xem phần Thêm mã qua một mẫu
Khi quá trình tạo hoàn tất, Android Studio sẽ mở các tệp AndroidManifest.xml và MapsActivity. Hoạt động của bạn có thể có tên khác, nhưng đó là tên bạn đã định cấu hình trong quá trình thiết lập.

Thận trọng: Tệp AndroidManifest.xml chứa hướng dẫn về cách lấy khoá API Google Maps rồi thêm khoá đó vào tệp local.properties. Không thêm khoá API vào tệp local.properties. Làm như vậy sẽ lưu trữ khoá API của bạn một cách kém an toàn hơn. Thay vào đó, hãy làm theo hướng dẫn trong phần Thiết lập dự án trên Google Cloud để tạo một dự án trên Cloud và định cấu hình khoá API.

Thiết lập dự án trên Google Cloud

Hoàn tất các bước thiết lập bắt buộc trên Cloud Console bằng cách nhấp vào các thẻ sau:

Bước 1

Giao diện dòng lệnh

Trong Google Cloud Console, trên trang chọn dự án, hãy nhấp vào Tạo dự án để bắt đầu tạo một dự án Cloud mới.

Chuyển đến trang chọn dự án
Đảm bảo bạn đã bật tính năng thanh toán cho dự án trên Cloud. Xác nhận rằng bạn đã bật tính năng thanh toán cho dự án của mình.

Google Cloud cung cấp bản dùng thử không tính phí. Thời gian dùng thử sẽ kết thúc sau 90 ngày hoặc sau khi tài khoản tích luỹ được khoản phí trị giá 3.000.000 VND, tuỳ theo điều kiện nào đến trước. Huỷ bất cứ lúc nào. Để biết thêm thông tin, hãy xem bài viết Khoản tín dụng trong tài khoản thanh toán và Thanh toán.

SDK đám mây

gcloud projects create "PROJECT"

Đọc thêm về Google Cloud SDK, quy trình cài đặt Cloud SDK và các lệnh sau:

gcloud projects create

Bước 2

Để sử dụng Nền tảng Google Maps, bạn phải bật các API hoặc SDK mà bạn dự định sử dụng cho dự án của mình.

Giao diện dòng lệnh

Bật Maps SDK cho Android

SDK đám mây

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

Đọc thêm về Google Cloud SDK, quy trình cài đặt Cloud SDK và các lệnh sau:

Bước 3

Bước này chỉ hướng dẫn quy trình tạo Khoá API. Nếu sử dụng Khoá API trong quá trình phát hành chính thức, bạn nên hạn chế Khoá API của mình. Bạn có thể tìm thêm thông tin trên trang Sử dụng khoá API dành riêng cho sản phẩm.

Khoá API là một giá trị nhận dạng duy nhất xác thực các yêu cầu liên kết với dự án của bạn cho mục đích sử dụng và thanh toán. Bạn phải có ít nhất một khoá API được liên kết với dự án của mình.

Cách tạo khoá API:

Giao diện dòng lệnh

Chuyển đến trang Nền tảng Google Maps > Thông tin đăng nhập.

Chuyển đến trang Thông tin đăng nhập
Trên trang Thông tin xác thực, hãy nhấp vào Tạo thông tin xác thực > Khoá API.
Hộp thoại Khoá API đã tạo sẽ hiển thị khoá API mới tạo.
Nhấp vào Đóng.
Khoá API mới sẽ xuất hiện trên trang Thông tin xác thực trong phần Khoá API.
(Hãy nhớ hạn chế API trước khi sử dụng khoá này trong quá trình phát hành công khai.)

SDK đám mây

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Đọc thêm về Google Cloud SDK, quy trình cài đặt Cloud SDK và các lệnh sau:

gcloud services api-keys create

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 kiểm soát phiên bản. Vì vậy, bạn nên lưu trữ khoá này 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 phần 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ặc build.gradle cấp cao nhất rồi thêm mã sau vào phần tử dependencies trong buildscript.

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ặc build.gradle ở cấp mô-đun rồi 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ặc build.gradle ở cấp mô-đun, hãy đảm bảo rằng targetSdk và compileSdk được đặt thành 34.
Đồ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, sau đó thêm đoạn 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.
Lưu ý: Nếu tệp secrets.properties không tồn tại, hãy tạo tệp đó trong cùng thư mục với tệp local.properties.
```
MAPS_API_KEY=YOUR_API_KEY
```
Tạo tệp local.defaults.properties trong thư mục cấp cao nhất (cùng thư mục với tệp secrets.properties), rồi thêm mã sau.

Lưu ý: Nhập mã như hình. Đừng thay thế DEFAULT_API_KEY bằng khoá API của bạn.
```
MAPS_API_KEY=DEFAULT_API_KEY
```
Mục đích của tệp này là cung cấp một vị trí sao lưu cho khoá API nếu không tìm thấy tệp secrets.properties để các bản dựng 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 kiểm soát phiên bản bỏ qua secrets.properties và bạn chưa tạo tệp secrets.properties cục bộ để cung cấp khoá API.
Trong tệp AndroidManifest.xml, hãy chuyển đến com.google.android.geo.API_KEY rồi cập nhật android:value attribute. Nếu thẻ <meta-data> không tồn tại, hãy tạo thẻ này dưới dạng 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 được đề xuất cho khoá API. Bạn có thể dùng một khoá có tên này để xác thực với nhiều API dựa trên Google Maps trên nền tảng Android, bao gồm cả Maps SDK cho Android. Để đảm bảo khả năng tương thích ngược, API này cũng hỗ trợ tên com.google.android.maps.v2.API_KEY. Tên cũ này chỉ cho phép xác thực với Android Maps API 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, 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ặc build.gradle ở cấp mô-đun rồi chỉnh sửa thuộc tính secrets. Nếu thuộc tính secrets 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ành secrets.properties, đặt defaultPropertiesFileName thành local.defaults.properties và đặt mọi thuộc tính 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"
}

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"
}

Xem mã

Kiểm tra mã do mẫu cung cấp. Cụ thể, hãy xem các tệp sau trong dự án Android Studio.

Tệp hoạt động trên Maps

Tệp hoạt động bản đồ là hoạt động chính của ứng dụng và chứa mã để quản lý cũng như hiển thị bản đồ. Theo mặc định, tệp xác định hoạt động có tên là MapsActivity.java hoặc nếu bạn đặt Kotlin làm ngôn ngữ cho ứng dụng của mình, thì tệp đó sẽ có tên là MapsActivity.kt.

Các phần tử chính của hoạt động trên bản đồ:

Đối tượng SupportMapFragment quản lý vòng đời của bản đồ và là phần tử mẹ của giao diện người dùng của ứng dụng.
Đối tượng GoogleMap cung cấp quyền truy cập vào dữ liệu và khung hiển thị bản đồ. Đây là lớp chính của Maps SDK dành cho Android. Hướng dẫn về Đối tượng trên bản đồ mô tả chi tiết hơn về các đối tượng SupportMapFragment và GoogleMap.
Hàm moveCamera đặt bản đồ ở giữa tại toạ độ LatLng cho Sydney, Úc. Các chế độ cài đặt đầu tiên cần định cấu hình khi thêm bản đồ thường là vị trí bản đồ và chế độ cài đặt camera; chẳng hạn như góc xem, hướng bản đồ và mức thu phóng. Hãy xem hướng dẫn về Camera và View để biết thông tin chi tiết.
Hàm addMarker sẽ thêm một điểm đánh dấu vào toạ độ của Sydney. Xem hướng dẫn về Dấu đánh dấu để biết thêm thông tin chi tiết.

Tệp Gradle của mô-đun

Tệp build.gradle.kts của Mô-đun bao gồm phần phụ thuộc bản đồ sau đây, đây là phần phụ thuộc bắt buộc của Maps SDK cho Android.

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

Để tìm hiểu thêm về cách quản lý phần phụ thuộc Maps, hãy xem phần Tạo phiên bản.

Tệp bố cục XML

Tệp activity_maps.xml là tệp bố cục XML xác định cấu trúc của giao diện người dùng ứng dụng. Tệp này nằm trong thư mục res/layout. Tệp activity_maps.xml khai báo một mảnh bao gồm các phần tử sau:

tools:context đặt hoạt động mặc định của mảnh thành MapsActivity, được xác định trong tệp hoạt động trên bản đồ.
android:name đặt tên lớp của mảnh thành SupportMapFragment. Đây là loại mảnh được dùng trong tệp hoạt động của bản đồ.

Tệp bố cục XML chứa mã sau:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

Triển khai và chạy ứng dụng

Ảnh chụp màn hình có bản đồ và điểm đánh dấu được căn giữa ở Sydney, Úc.

Khi bạn chạy ứng dụng thành công, ứng dụng sẽ hiển thị một bản đồ có tâm là Sydney, Úc, với một điểm đánh dấu trên thành phố như trong ảnh chụp màn hình sau.

Cách triển khai và chạy ứng dụng:

Trong Android Studio, hãy nhấp vào lựa chọn Run (Chạy) trong trình đơn (hoặc biểu tượng nút phát) để chạy ứng dụng.
Khi được nhắc chọn thiết bị, hãy chọn một trong các lựa chọn sau:
- Chọn thiết bị Android được kết nối với máy tính.
- Ngoài ra, hãy chọn nút chọn Launch emulator (Khởi chạy trình mô phỏng) rồi chọn thiết bị ảo mà bạn đã thiết lập.
Nhấp vào OK. Android Studio sẽ khởi động Gradle để tạo ứng dụng của bạn, sau đó hiển thị kết quả trên thiết bị hoặc trình mô phỏng. Có thể mất vài phút trước khi ứng dụng khởi chạy.

Các bước tiếp theo

Thiết lập bản đồ: Tài liệu này mô tả cách thiết lập các chế độ cài đặt ban đầu và thời gian chạy cho bản đồ, chẳng hạn như vị trí camera, loại bản đồ, thành phần giao diện người dùng và cử chỉ.
Thêm bản đồ vào ứng dụng Android (Kotlin): Lớp học lập trình này hướng dẫn bạn cách sử dụng một ứng dụng minh hoạ một số tính năng bổ sung của Maps SDK cho Android.
Sử dụng thư viện Maps Android KTX: Thư viện tiện ích Kotlin (KTX) này cho phép bạn tận dụng một số tính năng của ngôn ngữ Kotlin trong khi sử dụng Maps SDK cho Android.

Hướng dẫn nhanh về SDK Bản đồ dành cho Android Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Giới thiệu về môi trường phát triển

Thiết lập thiết bị Android

Tạo một dự án Google Maps trong Android Studio

Thiết lập dự án trên Google Cloud

Bước 1

Giao diện dòng lệnh

SDK đám mây

Bước 2

Giao diện dòng lệnh

SDK đám mây

Bước 3

Giao diện dòng lệnh

SDK đám mây

Thêm khoá API vào ứng dụng

Kotlin

Groovy

Kotlin

Groovy

Kotlin

Groovy

Xem mã

Tệp hoạt động trên Maps

Tệp Gradle của mô-đun

Tệp bố cục XML

Triển khai và chạy ứng dụng

Các bước tiếp theo

Hướng dẫn nhanh về SDK Bản đồ dành cho Android