Thiết lập dự án Android Studio

Trang này mô tả cách định cấu hình một dự án Android Studio để sử dụng Maps SDK cho Android mà không cần dùng mẫu Google Maps được trình bày chi tiết trong phần Bắt đầu nhanh.

Mẫu Google Maps sẽ tự động định cấu hình và thêm một 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ột mẫu Android Studio khác. Để làm như vậ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ột môi trường phát triển bằ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 Maps SDK 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:

  1. Trong tệp settings.gradle.kts cấp cao nhất, hãy thêm cổng trình bổ trợ Gradle, kho lưu trữ Google Maven và kho lưu trữ trung tâm Maven trong khối pluginManagement. Khối pluginManagement 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()
    }
}
  2. Trong tệp settings.gradle.kts cấp cao nhất, hãy thêm kho lưu trữ Maven của Google và kho lưu trữ trung tâm Maven trong khối dependencyResolutionManagement: 
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
  3. Trong tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun, hãy thêm phần phụ thuộc Dịch vụ Google Play cho Maps SDK 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:19.0.0"
}
  4. Trong tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun, hãy đặt compileSdk và minSdk thành các giá trị sau:

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 21
        // ...
    }
}

    Groovy

    android {
    compileSdk 34

    defaultConfig {
        minSdk 21
        // ...
    }
}
  5. Trong phần buildFeatures của tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun, hãy thêm lớp BuildConfig. Bạn có thể dùng lớp này để 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:

    Kotlin

    android {
  // ...
  buildFeatures {
    buildConfig = true
    // ...
  }
}

    Groovy

    android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}
  6. Trong tệp libs.versions.toml, hãy thêm nội dung sau: 
    [versions]
play-services-maps = "19.2.0"

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

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 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 và lưu trữ khoá API:

  1. Trong Android Studio, hãy mở tệp build.gradle ở cấp gốc rồi thêm đoạn mã sau vào phần tử dependencies trong buildscript.

    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")
    }
}
  2. Mở tệp build.gradle ở cấp ứng dụng rồi thêm đoạn mã sau vào phần tử plugins.

    Groovy

    plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    Kotlin

    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ở local.properties trong thư mục cấp dự án, sau đó thêm đoạn mã sau. Thay thế YOUR_API_KEY bằng khoá API của bạn. 
    MAPS_API_KEY=YOUR_API_KEY
  5. Trong tệp AndroidManifest.xml, hãy chuyển đến com.google.android.geo.API_KEY rồi 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 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ệ.

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 Dịch vụ Google Play

Thêm nội dung khai báo sau đây vào 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 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 lựa chọn là ACCESS_FINE_LOCATION (cung cấp thông tin vị trí chính xác của thiết bị) và ACCESS_COARSE_LOCATION (kém chính xác hơn). Để biết thông tin chi tiết, hãy 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 nhắm đến phiên bản 8.3 trở lên của SDK Dịch vụ Google Play, bạn không cần có quyền WRITE_EXTERNAL_STORAGE. Nếu nhắm đến các phiên bản trước của SDK Dịch vụ Google Play, 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 Legacy

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 nhắm đến API cấp 28 (Android 9.0) trở lên, thì bạn phải thêm khai báo sau trong phần tử <application> của AndroidManifest.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 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 Trình quản lý thiết bị ảo Android (AVD) đi kèm với Android Studio.

Bước 6: (Không bắt buộc) Kiểm tra xem có hỗ trợ Dịch vụ Play hay không

Maps SDK 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. Google cung cấp một phương thức mà bạn có thể gọi từ ứng dụng để 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 hay chưa.

Các bước tiếp theo

Sau khi định cấu hình dự án, bạn có thể thêm bản đồ.