設定

本頁說明您需要完成哪些設定，才能開始使用 Maps 3D SDK for Android 進行建構。設定程序包括設定 Google Cloud 專案和 API，以便與 SDK 搭配使用，然後設定 Android Studio 專案。請先完成這些步驟，再將第一個 3D 地圖新增至應用程式。

設定 Google Cloud 專案和 API 金鑰

您必須先完成下列步驟，設定 Google Cloud 專案和 API 金鑰，才能開始使用 Maps 3D SDK for Android 進行建構：

步驟 1

控制台

  1. 在 Google Cloud 控制台的專案選取器頁面中，按一下「建立專案」，開始建立新的 Cloud 專案。

    前往專案選取器頁面

  2. 確認 Cloud 專案已啟用計費功能。 確認專案已啟用計費功能。

    Google Cloud 提供免付費試用期。試用期將於 90 天後或帳戶費用累積達 $300 美元時 (以先發生者為準) 結束。您隨時可以取消試用。詳情請參閱「帳單帳戶抵免額」和「帳單」。

Cloud SDK

gcloud projects create "PROJECT"

進一步瞭解 Google Cloud SDK、Cloud SDK 安裝和下列指令：

步驟 2

如要使用 Google 地圖平台，您必須啟用打算在專案中使用的 API 或 SDK。

請注意，有些整合需要您啟用多個 API/SDK。如果您不確定要啟用哪些 API 或 SDK，請嘗試使用 API 選擇器，或查詢您要使用的 API/SDK 專用說明文件。

如要啟用一或多個 API 或 SDK，請按照下列步驟進行：

控制台

  1. 請前往 Cloud 控制台的「Maps API 程式庫」頁面，查看您可以啟用的 Google 地圖平台 API 和 SDK：

    前往 Maps API 程式庫頁面

  2. 按一下您要啟用的 API 或 SDK。
    • 如果按鈕顯示「啟用」，請按一下按鈕啟用該 API 或 SDK。
    • 如果按鈕顯示「管理」，表示 API 或 SDK 已啟用，您不需要再採取任何動作。
    • 按一下上述其中一個按鈕，畫面隨即會顯示該 API 或 SDK 的資訊主頁 (按一下「停用」按鈕，即可將該 API 或 SDK 從這個專案中移除)。

Cloud SDK

下列指令可啟用所有地圖、路線和地點 API：

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"

進一步瞭解 Google Cloud SDK、Cloud SDK 安裝和下列指令：

使用下列指令啟用 Environment API：

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

步驟 3

此步驟僅適用 API 金鑰建立程序。若您在正式環境中使用 API 金鑰，強烈建議您為 API 金鑰設定限制。詳情請參閱特定產品的「使用 API 金鑰」頁面。

API 金鑰是一組專屬 ID，用於驗證與您專案有關的使用權限及帳單處理要求。您的專案至少要有一個相關聯的 API 金鑰。

建立 API 金鑰的方法如下：

控制台

  1. 前往「Google Maps Platform」(Google 地圖平台) >「Credentials」(憑證) 頁面。

    前往「Credentials」(憑證) 頁面

  2. 在「Credentials」(憑證) 頁面上，點選「Create credentials」(建立憑證) >「API key」(API 金鑰)。
    「API key created」(建立的 API 金鑰) 對話方塊會顯示您新建立的 API 金鑰。
  3. 按一下「Close」(關閉)。
    新建立的 API 金鑰會出現在「Credentials」(憑證) 頁面的「API keys」(API 金鑰) 下方。
    (別忘了先為 API 金鑰設定限制，然後才在正式環境中使用)

Cloud SDK

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

進一步瞭解 Google Cloud SDK、Cloud SDK 安裝和下列指令：

如要啟用 SDK，請參閱 Google Cloud 控制台的 Maps 3D SDK for Android 頁面。如要進一步瞭解如何完成這些步驟，請參閱「開始使用 Google 地圖平台」一文。

設定 Android Studio 專案

本節將說明如何建立及設定 Android Studio 專案，以便與 Maps 3D SDK for Android 搭配使用。

第 1 部分：設定專案和 Gradle 設定

  1. 使用「Empty Views Activity」範本建立新的 Android Studio 專案。

  2. 如果您使用 Git 做為來源控管工具，請修改專案 .gitignore 檔案，避免將機密資料檔案提交至版本管控系統：

    • 在專案的根目錄中，開啟 .gitignore 檔案。
    • 新增下列程式碼：
    secrets.properties

  3. 更新專案層級的 build.gradle.kts 檔案：

    • 在專案的根目錄中，開啟 build.gradle.kts 檔案。
    • 在 plugins 區塊中，新增 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. 更新 gradle/libs.versions.toml 檔案： - 開啟 gradle/libs.versions.toml 檔案，通常位於專案根目錄中的 gradle 目錄。- 在版本部分中，新增 SDK 和 Secrets Gradle 外掛程式的版本：

    maps3dSdk = "0.0.1" # Update this value to match the SDK version to include
secretsGradlePlugin = "2.0.1"

    -   In the library section, add the SDK library:

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

    -   In the plugin section, add the Secrets Gradle plugin:

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

  5. 更新模組層級 app/build.gradle.kts 檔案： - 開啟模組層級 build.gradle.kts 檔案，通常位於 app 目錄中。 - 在檔案頂端，將 Secrets Gradle 外掛程式新增至 plugins 區塊：

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

    -   In the `dependencies` block, add the SDK:

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

    -   At the end of the file, outside of the `android` and `dependencies`
    blocks, add the secrets configuration:

    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"
}

第 2 部分：將 API 金鑰加進專案

  1. 建立 secrets.properties 檔案：

    • 在應用程式模組的根目錄 (通常是 app 目錄) 中，建立名為 secrets.properties 的新檔案。
    • 將 API 金鑰加入檔案：
    MAPS3D_API_KEY=YOUR_API_KEY_HERE
``` Note: Make sure you
    replace `YOUR_API_KEY_HERE` with the API key that you configured for use
with the Maps 3D SDK for Android.

  2. 建立 local.defaults.properties 檔案： - 在應用程式模組的根目錄中，建立名為 secrets.properties 的新檔案。- 在檔案中新增預設或預留位置 API 金鑰。這個檔案可登錄至版本管控系統：

    MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER

第 3 部分：更新 AndroidManifest.xml 檔案

  1. 開啟 app/src/main/AndroidManifest.xml 檔案。

  2. 在 <application> 標記內，<activity> 標記之前，新增下列 <meta-data> 元素，宣告 API 金鑰：

    <application
  ...>

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

  <activity
      ...>
  </activity>
</application>

    在建構程序期間，Secrets Gradle 外掛程式會將 ${MAPS3D_API_KEY} 預留位置替換為 secrets.properties 檔案中的金鑰。

後續步驟

設定好 Google Cloud 專案、API 金鑰和 Android Studio 專案，以便搭配 Maps 3D SDK for Android 使用後，您就可以在應用程式中新增 3D 地圖。