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 dành cho Android không 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 một Dự án Android Studio. Tuy nhiên, bạn cũng có thể thêm bản đồ vào dự án Android sử dụng mẫu Android Studio khác. Để thực hiện việc này, bạn cần tự định cấu hình dự án của bạn 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.

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 khác của Android Studio hoặc Gradle, bạn có thể phải sửa đổi các bước dựa trên những 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 Trình bổ trợ Android cho Gradle và khả năng tương thích với Android Studio.

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

Thư viện Maps SDK dành cho Android được cung cấp qua Kho lưu trữ Maven của Google. Người nhận thêm SDK vào ứng dụng, hãy làm như sau:

1. Trong tệp settings.gradle cấp cao nhất, hãy thêm phương thức 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 bất kỳ câu lệnh nào khác trong tập lệnh.

   pluginManagement {
       repositories {
           gradlePluginPortal()
           google()
           mavenCentral()
       }
   } 

2. Trong tệp settings.gradle cấp cao nhất, hãy thêm phương thức 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 ở cấp mô-đun, hãy thêm phần tử Phần phụ thuộc Dịch vụ Google Play đối với SDK bản đồ 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")
   }

4. Trong tệp build.gradle ở cấp mô-đun, hãy đặt compileSdk và minSdk thành các giá trị sau:
   Lưu ý: Hãy đảm bảo rằng compileSdk được được đặt thành 34 trở lên và minSdk được đặt thành cấp 21 trở lên.

   Groovy

   android {
       compileSdk 34
   
       defaultConfig {
           minSdk 21
           // ...
       }
   }

   Kotlin

   android {
       compileSdk = 34
   
       defaultConfig {
           minSdk = 21
           // ...
       }
   }

5. Trong phần buildFeatures của tệp build.gradle ở cấp mô-đun, thêm lớp BuildConfig mà bạn có thể dùng để truy cập 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 để bạn có thể tham chiếu khoá API một cách an toàn ứng dụng của bạn. Bạn không nên kiểm tra khoá API trong hệ thống quản lý phiên bản của mình. Vì vậy, bạn nên lưu trữ tệp này vào tệp secrets.properties. Tệp này 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.

Lưu ý: Hãy xem Trình bổ trợ Gradle Secrets cho Android tài liệu trên GitHub để biết các yêu cầu mới nhất về hệ thống và hướng dẫn cài đặ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ở build.gradle hoặc build.gradle.kts cấp cao nhất rồi thêm 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 mô-đun rồi thêm mã sau vào tệp 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")
   }

3. Trong tệp build.gradle ở cấp mô-đun, hãy đảm bảo rằng targetSdk và compileSdk được đặt 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 của bạn, sau đó thêm sau đây. 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 không được kiểm tra trong phần kiểm soát phiên bản hệ thống.
   Lưu ý: Nếu tệp secrets.properties không hãy tạo tệp này 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 bằng cách này làm tệp secrets.properties, rồi thêm mã sau.

   Lưu ý: Hãy nhập mã như hình minh hoạ. Khô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 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 quản lý phiên bản, trong đó 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, 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 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 name com.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.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.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 cài đặt cần thêm vào 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. Nội dung nhúng này 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 tùy chọn là ACCESS_FINE_LOCATION, cung cấp thông tin về 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 chi tiết, hãy xem dữ liệu vị trí.

Lưu ý: Tính năng khởi động 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 bạn đ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 bạn đang nhắm mục tiêu các phiên bản trước của SDK Dịch vụ Google Play, bạn phải yêu cầu WRITE_EXTERNAL_STORAGE quyền, trong phần tử manifest.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Thư viện Apache HTTP cũ

Nếu bạn đ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 bao gồm nội dung khai báo sau đây 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 SDK bản đồ dành cho Android, bạn phải triển khai ứng dụng đó cho thiết bị Android hoặc Android trình mô phỏng 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 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 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.
  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 những hồ sơ này hoàn toàn là CTS tuân thủ và có thể sử dụng các 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 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 có cài đặt Dịch vụ Google Play. Google cung cấp một phương pháp mà bạn có thể gọi từ ứng dụng của bạn để kiểm tra. Để biết thêm thông tin, hãy xem bài viết Kiểm tra xem Google Đã cài đặt các dịch vụ Play.

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