Maps SDK for Android 快速入門導覽課程

使用 Android Studio 適用的 Google 地圖 Views 範本，建立可顯示地圖的 Android 應用程式。如果想設定現有的 Android Studio 專案，請參閱「設定 Android Studio 專案」一文。

本快速入門導覽課程適用於熟悉 Kotlin 或 Java 基本 Android 開發作業的開發人員。

關於開發環境

本快速入門導覽課程在製作時，使用的是 Android Studio Hedgehog 和 Android Gradle 外掛程式 8.2 版。

注意：如果您的開發環境使用其他版本的 Android Studio 或 Gradle，可能就需要修改步驟。如要進一步瞭解各種 Android Studio 和 Gradle 版本，請參閱「Android Gradle 外掛程式和 Android Studio 相容性」一節。

設定 Android 裝置

如要執行使用 Maps SDK for Android 的應用程式，請務必將該應用程式部署至採用 Android 5.0 以上版本且包含 Google API 的 Android 裝置或 Android 模擬器。

• 如要使用 Android 裝置，請按照在硬體裝置上執行應用程式一文的說明操作。
• 如要使用 Android 模擬器，您可以使用 Android Studio 隨附的 Android 虛擬裝置管理工具 (AVD Manager) 建立虛擬裝置並安裝模擬器。
  注意：如果您選擇使用 Android 模擬器，請務必選擇標有「Google Play」圖示 的裝置，這個圖示會顯示在「Play 商店」欄下方。上述圖示代表裝置完全符合 CTS 規定，且可使用包含 Play 商店應用程式的系統映像檔：

  

在 Android Studio 建立 Google 地圖專案

在 Android Studio 建立 Google 地圖專案的步驟，在 Flamingo 和較新版的 Android Studio 已有所調整。

1. 開啟 Android Studio，然後在「Welcome to Android Studio」視窗中按一下「New Project」。

2. 在「New Project」(新增專案) 視窗中的「Phone and Tablet」(手機和平板電腦) 類別下方，選取「No Activity」(無活動)，然後點選「Next」(下一步)。

3. 填寫「New Project」(新增專案) 表單：

   • 將「Language」(語言) 設為 Java 或 Kotlin。Maps SDK for Android 全面支援這兩種語言。如要進一步瞭解 Kotlin，請參閱「使用 Kotlin 開發 Android 應用程式」一文。

   • 將「Minimum SDK」(SDK 最低版本) 設為與測試裝置相容的 SDK 版本。您所選的版本必須高於 Maps SDK for Android 19.0.x 版所需的最低版本，也就是 Android API 級別 21 (「Lollipop」；Android 5.0) 以上版本。如想瞭解 SDK 版本需求條件的最新資訊，請參閱「版本資訊」一文。

     注意：如果不確定該選擇哪個 SDK 版本，請選取「Help me choose」(請幫我選擇) 連結，查看所支援 Android SDK 的發布資訊。舉例來說，如果您選擇「Android API Level 21 ("Lollipop"; Android 5.0)」，您的應用程式應該能在 99% 的 Android 裝置上執行。

   • 將「Build configuration language」(建構設定語言) 設為 Kotlin DSL 或 Groovy DSL，這兩種建構設定語言的程式碼片段隨即會顯示在下列程序中。

4. 按一下「Finish」(完成)。

   Android Studio 會啟動 Gradle，並開始建構專案。這個過程需要一點時間，請耐心等待。

5. 新增「Google Maps Views Activity」(Google 地圖檢視畫面活動)：

   1. 對著專案中的 app 資料夾按一下滑鼠右鍵。

   2. 依序選取「New」(新增) >「Google」>「Google Maps Views Activity」(Google 地圖檢視畫面活動)。

      

   3. 在「New Android Activity」(新增 Android 活動) 對話方塊中，勾選「Launcher Activity」(啟動器活動) 核取方塊。

   4. 選取「Finish」(完成)。

      詳情請參閱「加入範本中的程式碼」一文。

6. 建構完成後，Android Studio 會開啟 AndroidManifest.xml 和 MapsActivity 檔案。活動的名稱可能會改變，但會是您在設定期間採用的名稱。

   注意：您可依據 AndroidManifest.xml 檔案內的操作說明，取得 Google Maps API 金鑰並加進 local.properties 檔案。請勿直接將 API 金鑰加入 local.properties 檔案中，因為用這種方式保存 API 金鑰不夠安全。反之，請依據「設定 Google Cloud 專案」一文中的操作說明，建立 Cloud 專案並設定 API 金鑰。

設定 Google Cloud 專案

請點選以下分頁標籤，完成必要的 Cloud 控制台設定步驟：

步驟 1

控制台

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

   前往專案選取器頁面

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

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

Cloud SDK

gcloud projects create "PROJECT"

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

• gcloud projects create

注意：如果您不打算保留練習期間建立的資源，請建立新專案，不要選取現有專案。這樣當您完成練習後，就可以直接刪除該專案，並移除相關聯的所有資源。

步驟 2

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

控制台

啟用 Maps SDK for Android

Cloud SDK

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

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

• gcloud services enable
• gcloud services disable

步驟 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 alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

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

• gcloud alpha services api-keys create

在應用程式中加入 API 金鑰

本節將說明如何儲存 API 金鑰，讓應用程式以安全的方式參照金鑰。API 金鑰不應該登錄在版本管控系統中；我們建議將金鑰儲存在位於專案根目錄的 secrets.properties 檔案內。如要進一步瞭解 secrets.properties 檔案，請參閱這篇文章中關於 Gradle 屬性檔案的說明。

建議您使用 Secrets Gradle Plugin for Android 來簡化這項工作。

注意：請參閱 GitHub 的「Secrets Gradle Plugin for Android」說明文件，瞭解最新系統需求和安裝操作說明。

如要在 Google 地圖專案中安裝 Secrets Gradle Plugin for Android，請按照下列步驟操作：

1. 在 Android Studio 中開啟頂層的 build.gradle.kts 或 build.gradle 檔案， 然後將下列程式碼加進 buildscript 下方的 dependencies 元素。

   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. 開啟模組層級的 build.gradle.kts 或 build.gradle 檔案，然後將下列程式碼加進 plugins 元素。

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. 在模組層級的 build.gradle.kts 或 build.gradle 檔案中，確認 targetSdk 和 compileSdk 已設為 34。
4. 儲存檔案，然後使用 Gradle 同步處理專案。
5. 開啟頂層目錄中的 secrets.properties 檔案，並加入下列程式碼，然後將 YOUR_API_KEY 替換成您的 API 金鑰。secrets.properties 不會登錄在版本管控系統中，因此請將金鑰儲存至該檔案。
   注意： 如果 secrets.properties 檔案不存在，請在 local.properties 檔案所屬的資料夾中建立一個。

   MAPS_API_KEY=YOUR_API_KEY

6. 儲存檔案。

7. 在頂層目錄 (與 secrets.properties 檔案相同的資料夾) 中建立 local.defaults.properties 檔案，然後加入下列程式碼。

   注意：輸入的程式碼必須與下列內容完全一致。請勿將 DEFAULT_API_KEY 替換成您的 API 金鑰。

   MAPS_API_KEY=DEFAULT_API_KEY

   如果找不到 secrets.properties 檔案，這個檔案便可做為 API 金鑰的備份位置，以確保建置程序不會失敗。如果您從略過 secrets.properties 的版本管控系統複製應用程式，且尚未在本機建立 secrets.properties 檔案來提供 API 金鑰，就可能會發生這種情況。

8. 儲存檔案。
9. 找到 AndroidManifest.xml 檔案中的 com.google.android.geo.API_KEY，並更新 android:value attribute。如果沒有 <meta-data> 標記，請以 <application> 標記子項的形式建立該標記。

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

   注意： com.google.android.geo.API_KEY 是 API 金鑰的建議中繼資料名稱。具備這個名稱的金鑰可用來驗證 Android 平台上的多個 Google 地圖相關 API，包括 Maps SDK for Android。為了兼顧回溯相容性，API 也支援 com.google.android.maps.v2.API_KEY 這個名稱。此舊版名稱僅允許對 Android Maps API 第 2 版進行驗證。應用程式只能指定這兩種 API 金鑰中繼資料名稱的其中一個；如果同時指定兩者，API 就會擲回例外狀況。

10. 在 Android Studio 中開啟模組層級的 build.gradle.kts 或 build.gradle 檔案，然後編輯 secrets 屬性。如果找不到 secrets 屬性，請新增該屬性。

    編輯外掛程式的屬性，將 propertiesFileName 設為 secrets.properties、將 defaultPropertiesFileName 設為 local.defaults.properties，並設定任何其他屬性。

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

查看程式碼

檢查範本提供的程式碼。請特別留意 Android Studio 專案中的下列檔案。

地圖活動檔案

地圖活動檔案是應用程式的主要「活動」，其中含有管理和顯示地圖的程式碼。根據預設，定義活動的檔案名稱為 MapsActivity.java；如果您將 Kotlin 設為應用程式的語言，則為 MapsActivity.kt。

地圖活動的主要元素：

• SupportMapFragment 物件會管理地圖的生命週期，且是應用程式使用者介面的父項元素。

• GoogleMap 物件提供地圖資料和檢視畫面的存取權。這是 Maps SDK for Android 的主要類別。地圖物件指南將詳細說明 SupportMapFragment 和 GoogleMap 物件。

• moveCamera 函式，會把地圖中心設在澳洲雪梨的 LatLng 座標。新增地圖時，第一個要設定的通常是地圖位置和相機設定，例如視角、地圖方向和縮放等級。詳情請參閱相機和檢視畫面指南。

• addMarker 函式會為雪梨的座標新增標記。詳情請參閱標記指南。

Gradle 模組檔案

模組 build.gradle.kts 檔案包含下列地圖依附元件；該元件是 Maps SDK for Android 的必要資料。

dependencies {

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

注意： 視 Maps SDK for Android 目前版本而定，實際版本可能不同。

如要進一步瞭解如何管理地圖依附元件，請參閱「版本管理」一文。

XML 版面配置檔案

activity_maps.xml 檔案是定義應用程式使用者介面結構的 XML 版面配置檔案。這個檔案位於 res/layout 目錄中。activity_maps.xml 檔案會宣告內含下列元素的片段：

• tools:context 會將片段的預設活動設為 MapsActivity，並在地圖活動檔案中定義。
• android:name 會將片段的類別名稱設為 SupportMapFragment，也就是地圖活動檔案中所使用的片段類型。

XML 版面配置檔案內含以下程式碼：

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

部署及執行應用程式

成功執行應用程式時，這個應用程式會顯示以澳洲雪梨為中心的地圖，其中城市上方有標記，如下方的螢幕截圖所示。

部署及執行應用程式的方法如下：

1. 在 Android Studio 中，按一下「Run」(執行) 選單選項 (或播放按鈕圖示)，執行應用程式。
2. 系統提示您選擇裝置時，請選擇下列其中一個選項：
   • 選取與您電腦連結的 Android 裝置。
   • 或者，選取「Launch emulator」(啟動模擬器) 圓形按鈕，然後選擇您設定的虛擬裝置。
3. 按一下「OK」(確定)。Android Studio 會啟動 Gradle 來建構應用程式，然後在裝置或模擬器上顯示搜尋結果。啟動應用程式可能需要幾分鐘的時間。

後續步驟

• 設定地圖：本文件說明如何進行地圖的初始和執行階段設定，例如相機位置、地圖類型、使用者介面元件和手勢。

• 在 Android 應用程式中加入地圖 (Kotlin)：這個程式碼研究室將逐步引導您使用應用程式，並示範 Maps SDK for Android 的其他功能。

• 使用 Maps Android KTX 程式庫：這個 Kotlin 擴充功能 (KTX) 程式庫可讓您在使用 Maps SDK for Android 時，運用數種 Kotlin 語言功能。