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 Chế độ xem của Google Maps cho Android Studio. Nếu bạn có một dự án Android Studio hiện có 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 bắt đầu nhanh này dành cho những nhà phát triển Android đã quen thuộc với kiến thức cơ bản về phát triển Android bằng Kotlin hoặc Java.

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

Bạn nên sử dụng phiên bản ổn định mới nhất của Android Studio và Trình bổ trợ Android cho Gradle.

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 6.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 Trình quản lý thiết bị đi kèm với Android Studio.

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

  1. 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).

  2. 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).

  3. Hoàn tất biểu mẫu New Project (Dự án mới):

    • Đặt Language (Ngôn ngữ) thành Java hoặc Kotlin. Cả hai ngôn ngữ đều được SDK Maps cho Android hỗ trợ đầy đủ. Để tìm hiểu thêm về Kotlin, hãy xem bài viết 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 cao hơn phiên bản tối thiểu mà Maps SDK cho Android phiên bản 20.0.x yêu cầu, tức là cấp độ API Android 23 ("Marshmallow"; Android 6.0) trở lên. 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.

    • Đặt Build configuration language (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 được trình bày trong các quy trình sau.

  4. 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.

  5. Thêm Hoạt động xem trên Google Maps:

    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):

      Trình đơn theo bối cảnh của Android Studio cho thư mục ứng dụng cho thấy các mục New (Mới), Google và Google Maps Views Activity (Hoạt động của Chế độ xem Google Maps) đã chọn.
      Thêm Hoạt động của Chế độ xem Google Maps từ trình đơn theo bối cảnh app trong Android Studio.

    3. Trong hộp thoại New Android Activity (Hoạt động mới trên Android), hãy chọn hộp đánh dấu 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.

  6. Khi quá trình tạo bản dựng 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, tuỳ thuộc vào nội dung bạn đã định cấu hình trong quá trình thiết lập.

Thiết lập dự án trên đám mây của bạn

Hoàn tất các bước thiết lập bắt buộc sau đây trong Cloud Console:

Bước 1: Thiết lập dự án

Giao diện dòng lệnh

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

    Chuyển đến trang bộ chọn dự án

  2. Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên đám mây của bạn. 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 gói 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 300 USD phí, 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 phần Tín dụng 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, cách cài đặt Cloud SDK và các lệnh sau:

Bước 2: Bật API hoặc SDK

Để sử dụng Google Maps Platform, bạn phải bật các API hoặc SDK mà bạn dự định 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, cách cài đặt Cloud SDK và các lệnh sau:

Bước 3: Lấy khoá API

Bước này chỉ thực hiện quy trình tạo khoá API. Nếu sử dụng khoá API trong môi trường thực tế, 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 riêng biệt giúp xác thực các yêu cầu liên quan đến 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 liên kết với dự án của mình. Để tạo khoá mới hoặc thêm API hay SDK vào khoá hiện có, hãy làm theo các hướng dẫn sau.

Giao diện dòng lệnh

  1. Chuyển đến trang Google Maps Platform > Khoá và thông tin xác thực.

    Chuyển đến trang Khoá và thông tin xác thực

  2. Nếu thấy lời nhắc, hãy chọn dự án của bạn.

  3. Thực hiện một trong các thao tác sau:

    • Tạo khoá mới:

      1. Nhấp vào Tạo thông tin xác thực > Khoá API.
      2. Trong bảng điều khiển Create API key (Tạo khoá API), hãy mở danh sách Select API restrictions (Chọn các quy định hạn chế đối với API).
      3. Xoá mọi API mà khoá này không cần, đồng thời đảm bảo Maps SDK cho Android vẫn được chọn.
      4. Nhấp vào Tạo. Bảng điều khiển sẽ hiển thị khoá API mới của bạn.

    • Sử dụng khoá hiện có:

      1. Nhấp vào tên của khoá.
      2. Trong danh sách Chọn các quy định hạn chế đối với API, hãy chọn Maps SDK cho Android.
      3. Nhấp vào Lưu.

    Việc chọn một API ở đây không giúp bật API đó. Đảm bảo Maps SDK cho Android được bật trên trang Thư viện API.

  4. Để xem chuỗi khoá sau này, hãy chuyển đến trang Khoá và thông tin xác thực rồi nhấp vào Hiện khoá cho khoá đó.

Nếu bảng điều khiển có giao diện khác với các bước này, hãy xem phần Tạo khoá API và Thêm quy định hạn chế về API trong tài liệu của Google Cloud.

SDK đám mây

Thay thế PROJECT_ID bằng mã dự án của bạn trong các lệnh sau.

  • Tạo khoá mới: Chạy lệnh sau và thay thế DISPLAY_NAME bằng tên cho khoá. 

    gcloud services api-keys create \
    --project="PROJECT_ID" \
    --display-name="DISPLAY_NAME" \
    --api-target=service=maps-android-backend.googleapis.com

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

  • Sử dụng khoá hiện có: Chạy lệnh sau và thay thế KEY_ID bằng mã nhận dạng của khoá. Cờ --append giữ lại các API mà khoá đã cho phép. Nếu không có, lệnh sẽ thay thế các tệp đó.

    gcloud services api-keys update KEY_ID \
    --project="PROJECT_ID" \
    --append \
    --api-target=service=maps-android-backend.googleapis.com

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

    Mã khoá không phải là chuỗi khoá hoặc tên hiển thị. Để tìm tệp này, hãy chạy gcloud services api-keys list --project="PROJECT_ID". Mã nhận dạng là phần cuối cùng của trường name: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

Để xem chuỗi khoá, hãy chạy gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

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 đưa khoá API vào hệ thống quản lý phiên bản. Do đó, bạn nên lưu trữ khoá API trong tệp secrets.properties trong thư mục gốc của dự án và loại trừ tệp đó khỏi hệ thống quản lý phiên bản. Để biết thêm thông tin về tệp thuộc tính Gradle, hãy xem phần Tệp thuộc tính Gradle.

Để đơn giản hoá việc 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 và lưu trữ khoá API:

  1. 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 khối 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. Mở tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun rồi thêm mã sau vào phần tử 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. Nếu bạn sử dụng Android Studio, hãy đồng bộ hoá dự án với Gradle.
  4. Mở tệp secrets.properties trong thư mục cấp cao nhất, rồi thêm đoạn mã sau. Thay thế YOUR_API_KEY bằng khoá API của bạn. Hãy nhớ thêm secrets.properties vào tệp .gitignore (hoặc loại trừ tệp này khỏi hệ thống quản lý phiên bản) để không đưa khoá API vào hệ thống quản lý phiên bản. 
    MAPS_API_KEY=YOUR_API_KEY

  5. 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.

    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 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.

  6. Trong tệp AndroidManifest.xml, hãy chuyển đến com.google.android.geo.API_KEY và cập nhật thuộc tính android:value như sau: 
    <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 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ả SDK Maps cho Android. Để 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 của khoá API. Nếu bạn chỉ định cả hai, API sẽ gửi một ngoại lệ.

  7. 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 này.

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

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 của bạn.

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

Tệp hoạt động trên Maps 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 thì tệp đó có tên là MapsActivity.kt.

Các thành phần chính của hoạt động trên Maps:

  • Đố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à chế độ xem bản đồ. Đây là lớp chính của Maps SDK cho Android. Hướng dẫn về Đối tượng 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 toạ độ LatLng của Sydney, Ú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à Chế độ xem để biết thêm thông tin chi tiết.

  • Hàm addMarker thêm một điểm đánh dấu vào toạ độ của Sydney. Xem hướng dẫn về Điểm đánh dấu để biết thêm thông tin chi tiết.

Kotlin

// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"),
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

Java

// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

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

Tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun bao gồm phần phụ thuộc Maps sau đây, bắt buộc phải có trong SDK Maps cho Android.

Kotlin

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

Groovy

dependencies {

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

Nếu dự án của bạn sử dụng danh mục phiên bản Gradle (gradle/libs.versions.toml), hãy xác định phần phụ thuộc play-services-maps trong libs.versions.toml:

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

Để tìm hiểu thêm về cách quản lý phần phụ thuộc của 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 giao diện người dùng của ứ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 fragment thành MapsActivity, được xác định trong tệp hoạt động trên Maps.
  • android:name đặt tên lớp của fragment thành SupportMapFragment, đây là loại fragment được dùng trong tệp hoạt động trên Maps.

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 ở 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.

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

  1. Trong Android Studio, hãy nhấp vào mục Run (Chạy) trong trình đơn (hoặc biểu tượng nút phát) để chạy ứng dụng.
  2. Khi được nhắc chọn một 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 (Chạy trình mô phỏng) rồi chọn thiết bị ảo mà bạn đã thiết lập.
  3. Nhấp vào OK. Android Studio sẽ khởi động Gradle để tạo ứng dụng, sau đó hiển thị kết quả trên thiết bị hoặc trình mô phỏng của bạn. 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 về 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 khi sử dụng Maps SDK cho Android.