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

Trang này mô tả cách định cấu hình dự án Android Studio để sử dụng SDK Maps cho Android mà không cần sử dụng mẫu Google Maps được mô tả 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 sử dụng Android Studio Hedgehog và trình bổ trợ Android cho Gradle phiên bản 8.2.

Lưu ý: Nếu môi trường phát triển của bạn sử dụng một phiên bản Android Studio hoặc Gradle khác, thì bạn có thể phải sửa đổi các bước dựa trên các phiên bản đó. Để biết thêm thông tin về các phiên bản Android Studio và Gradle, hãy xem phần Khả năng tương thích của trình bổ trợ Android cho Gradle và Android Studio.

Bước 2. Thiết lập SDK

Thư viện SDK Bản đồ 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:

1. Trong tệp settings.gradle.kts cấp cao nhất, hãy thêm 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ố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 vào 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 SDK Maps dành cho Android.

   Kotlin

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

   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:
   Lưu ý: Đảm bảo rằng compileSdk được đặt thành 34 trở lên và minSdk được đặt thành 21 trở lên.

   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 mà bạn có thể sử 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:

   Kotlin

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

   Groovy

   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 khoá đó một cách an toàn. Bạn không nên kiểm tra khoá API vào 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 phần Tệp thuộc tính Gradle.

Để đơn giản hoá nhiệm vụ này, bạn nên sử dụng Trình bổ trợ Secrets Gradle cho Android.

Lưu ý: Hãy xem tài liệu về Trình bổ trợ Secrets Gradle cho Android trên GitHub để biết các yêu cầu hệ thống và hướng dẫn cài đặt mới nhất.

Cách cài đặt Trình bổ trợ Secrets Gradle cho Android trong dự án Google Maps:

1. Trong Android Studio, hãy mở tệp build.gradle.kts hoặc build.gradle cấp cao nhất và 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"
       }
   }

2. Mở tệp build.gradle.kts hoặc build.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'
   }

3. Trong tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun, hãy đảm bảo rằng bạn đặt targetSdk và compileSdk thành 34.
4. Lưu tệp và đồng bộ hoá dự án với Gradle.
5. Mở tệp secrets.properties trong thư mục cấp cao nhất, 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.
   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

6. Lưu tệp.

7. 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, sau đó thêm mã sau.

   Lưu ý: Nhập mã như minh hoạ. Đừng thay thế DEFAULT_API_KEY bằng khoá API.

   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 nhân bản ứng dụng từ một hệ thống quản lý 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.

8. Lưu tệp.
9. 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 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 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 v2. 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 ngoại lệ.

10. Trong Android Studio, hãy mở tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun và 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 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.*"
    }
            

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

Lưu ý: Hướng dẫn bắt đầu nhanh đã bật ACCESS_FINE_LOCATION.

Để 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, bạn không cần quyền WRITE_EXTERNAL_STORAGE. Nếu đang nhắm đến các phiên bản SDK Dịch vụ Google Play cũ hơn, 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 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ủ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 SDK Maps 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à 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 tại 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, , hiển thị trong cột Cửa hàng Play. Biểu tượng này cho biết rằng 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:

  

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

SDK Maps 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 của mình để kiểm tra. Để biết thêm thông tin, hãy xem phần Kiểm tra xem bạn đã cài đặt Dịch vụ Google Play 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 đồ.