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

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í. Bản dùng thử sẽ hết hạn sau 90 ngày hoặc sau khi tài khoản đã tích luỹ được khoản phí trị giá 300 USD, 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ài đặt Cloud SDK và các lệnh sau:

• gcloud projects create

Lưu ý: Nếu bạn không định giữ lại các tài nguyên mà bạn tạo trong một bài tập học tập, hãy tạo một dự án thay vì chọn một dự án hiện có. Sau khi hoàn thành bài tập, bạn có thể xoá dự án và xoá tất cả tài nguyên liên kết với dự án đó.

Bước 2

Để 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:

Giao diện dòng lệnh

1. Xem các API và SDK của Google Maps Platform mà bạn có thể bật bằng cách truy cập vào trang Thư viện API Maps trong Cloud Console:

   Chuyển đến trang Thư viện API Maps

2. Nhấp vào API hoặc SDK mà bạn muốn bật.
   • Nếu nút này có nhãn BẬT, hãy nhấp vào nút đó để bật API hoặc SDK.
   • Nếu nút này có nhãn MANAGE (QUẢN LÝ), thì tức là API hoặc SDK đã được bật và bạn không cần làm gì thêm.
   • Khi nhấp vào một trong hai nút, bạn sẽ thấy trang tổng quan của API hoặc SDK. (Nhấp vào nút TẮT để xoá API hoặc SDK khỏi dự án này.)

SDK đám mây

Lệnh sau đây bật tất cả các API Maps, Routes và Places:

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"

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

• gcloud services enable
• gcloud services disable

Sử dụng lệnh này để bật Environment API:

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

Lưu ý: Khi bật Places API, bạn cũng sẽ bật Thư viện địa điểm, Maps JavaScript API, SDK Địa điểm cho Android và SDK Địa điểm cho iOS.

Bước 3

Bước này chỉ hướng dẫ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.

Cách tạo khoá API:

Giao diện dòng lệnh

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

   Chuyển đến trang Thông tin đăng nhập

2. Trên trang Thông tin xác thực, hãy nhấp vào Tạo thông tin xác thực > Khoá API.
   Hộp thoại Đã tạo khoá API sẽ hiển thị khoá API bạn vừa tạo.
3. Nhấp vào Đóng.
   Khoá API mới sẽ xuất hiện trên trang Thông tin xác thực trong phần Khoá API.
   (Nhớ hạn chế khoá API trước khi sử dụng trong phiên bản chính thức.)

SDK đám mây

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

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

• gcloud services api-keys create

Để 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
   

   Lưu ý: Hãy nhớ thay thế YOUR_API_KEY_HERE bằng khoá API mà bạn đã định cấu hình để sử dụng với SDK Maps 3D dành cho Android.

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.