Thiết lập

Trang này mô tả những việc bạn cần làm để thiết lập và bắt đầu xây dựng bằng Maps 3D SDK cho Android. Quá trình thiết lập bao gồm việc định cấu hình một dự án Google Cloud và API để sử dụng với SDK, sau đó thiết lập một dự án Android Studio. Hãy hoàn tất các bước này trước khi thêm bản đồ 3D đầu tiên vào ứng dụng.

Điều kiện tiên quyết

Để sử dụng Maps 3D SDK cho Android, dự án và thiết bị mục tiêu của bạn phải đáp ứng các yêu cầu sau:

• Cấp độ API tối thiểu: API Android cấp 24 (Android 7.0) trở lên. Ứng dụng của bạn phải nhắm đến minSdk từ 24 trở lên.
• Dịch vụ Google Play: SDK Maps 3D dành cho Android phụ thuộc vào Dịch vụ Google Play. Thiết bị mục tiêu (và trình mô phỏng có API Google) phải cài đặt Dịch vụ Google Play.

Thiết lập dự án trên đám mây của Google Cloud và khoá API

Trước khi có thể bắt đầu xây dựng bằng Maps 3D SDK cho Android, bạn cần thiết lập một dự án trên Google Cloud và khoá API để sử dụng với Maps 3D SDK cho Android bằng cách hoàn tất các bước sau:

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

gcloud projects create "PROJECT"

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.

Xin lưu ý rằng một số hoạt động tích hợp yêu cầu bạn bật nhiều API/SDK. Nếu bạn không chắc chắn nên bật API hoặc SDK nào, hãy thử sử dụng Trình khám phá chức năng hoặc tham khảo tài liệu về API/SDK mà bạn muốn sử dụng.

Cách bật một hoặc nhiều API hoặc SDK:

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-backend.googleapis.com"

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.googleapis.com"

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.

Để bật SDK, hãy xem trang SDK Maps 3D dành cho Android trong Google Cloud Console. Để biết thêm thông tin về cách hoàn tất các bước này, hãy xem bài viết Bắt đầu sử dụng Google Maps Platform.

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

Phần này giải thích cách tạo và định cấu hình một dự án Android Studio để sử dụng với Maps 3D SDK cho Android.

Phần 1: Thiết lập dự án và cấu hình Gradle

1. Tạo một dự án Android Studio mới bằng mẫu Empty Views Activity (Hoạt động trống trong Khung hiển thị). Trong cấu hình dự án, hãy đặt SDK tối thiểu thành API 24 trở lên.

2. Nếu bạn đang sử dụng Git để kiểm soát nguồn, hãy sửa đổi tệp .gitignore của dự án để ngăn tệp bí mật của bạn được đưa vào hệ thống quản lý phiên bản:

   • Trong thư mục gốc của dự án, hãy mở tệp .gitignore.
   • Hãy thêm dòng lệnh sau đây:

   secrets.properties
   

3. Cập nhật tệp build.gradle.kts cấp dự án:

   • Trong thư mục gốc của dự án, hãy mở tệp build.gradle.kts.
   • Trong khối plugins, hãy thêm trình bổ trợ Secrets Gradle:

   plugins {
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
   }
   

4. Cập nhật tệp gradle/libs.versions.toml:

   • Mở tệp gradle/libs.versions.toml, thường nằm trong thư mục gradle trong thư mục gốc của dự án.
   • Trong phần [versions], hãy thêm các phiên bản cho SDK và trình bổ trợ Secrets cho Gradle:

   # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
   maps3dSdk = "16.0.1"
   # See https://github.com/google/secrets-gradle-plugin/releases for available releases
   secretsGradlePlugin = "2.0.1"
   

   • Trong phần [library], hãy thêm thư viện SDK:

   play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
   

   • Trong phần [plugins], hãy thêm trình bổ trợ Secrets Gradle:

   secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }
   

5. Cập nhật tệp app/build.gradle.kts cấp mô-đun:

   • Mở tệp build.gradle.kts ở cấp mô-đun, thường nằm trong thư mục app.
   • Ở đầu tệp, hãy thêm trình bổ trợ Secrets Gradle vào khối plugins:

   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.secrets.gradle.plugin) // Add this line
   }
   

   • Trong khối dependencies, hãy thêm phần phụ thuộc Dịch vụ Google Play cho SDK Maps 3D cho Android:

   dependencies {
       // ... other dependencies
       implementation(libs.play.services.maps3d) // Add this line
   }
   

   • Ở cuối tệp, bên ngoài các khối android và dependencies, hãy thêm cấu hình bí mật:

   secrets {
       // Optionally specify a different filename 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"
   }
   

Phần 2: Thêm khoá API vào dự án

1. Tạo tệp secrets.properties:

   • Trong thư mục gốc của mô-đun ứng dụng (thường là thư mục app), hãy tạo một tệp mới có tên là secrets.properties.
   • Thêm khoá API vào tệp:

   MAPS3D_API_KEY=YOUR_API_KEY_HERE
   

2. Tạo tệp local.defaults.properties: - Trong thư mục gốc của mô-đun ứng dụng, hãy tạo một tệp mới có tên là local.defaults.properties. – Thêm khoá API mặc định hoặc khoá API phần giữ chỗ vào tệp. Bạn có thể kiểm tra tệp này trong phần quản lý phiên bản:

   MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
   

Phần 3: Cập nhật tệp AndroidManifest.xml

1. Mở tệp app/src/main/AndroidManifest.xml.

2. Bên trong thẻ <application>, trước thẻ <activity>, hãy thêm phần tử <meta-data> sau đây để khai báo khoá API:

   <application
       ...>
   
       <meta-data
           android:name="com.google.android.geo.maps3d.API_KEY"
           android:value="${MAPS3D_API_KEY}" />
   
       <activity
           ...>
       </activity>
   </application>
   

   Trong quá trình tạo bản dựng, Trình bổ trợ Gradle cho bí mật sẽ thay thế phần giữ chỗ ${MAPS3D_API_KEY} bằng khoá trong tệp secrets.properties của bạn.

Khởi chạy chế độ xem có lập trình (không bắt buộc)

Nếu bạn muốn khởi chạy chế độ xem bản đồ theo phương thức lập trình thay vì trong bố cục XML, hãy sử dụng Map3DInitConfig.

import com.google.android.gms.maps3d.Map3DInitConfig
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.model.Map3DMode

// Set configuration options using the factory method
val config = Map3DInitConfig.create(
    mapMode = Map3DMode.HYBRID,
    centerLat = 38.544012,
    centerLng = -107.670428
)

val map3DView = Map3DView(context, config)

Các bước tiếp theo

Giờ đây, khi đã có một dự án trên Google Cloud, khoá API và một dự án Android Studio được thiết lập để sử dụng với Maps 3D SDK cho Android, bạn có thể Thêm bản đồ 3D vào ứng dụng của mình.