設定 Android Studio 專案

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

本頁說明如何在不採用快速入門導覽課程中詳述的 Google 地圖範本的情況下,將 Android Studio 專案設為使用 Maps SDK for Android

Google 地圖範本會自動設定基本地圖,並將其加進新的 Android Studio 專案,但您也可以將地圖新增至使用其他 Android Studio 範本的 Android 專案。如要這麼做,您需要手動設定專案,然後新增地圖

步驟 1:設定 Android Studio

  1. 必須使用 Android Studio Arctic Fox 或更新版本。如果您尚未下載安裝,請先完成此步驟。
  2. 確認您在 Android Studio 中使用的是 Android Gradle 外掛程式 7.0 以上版本

步驟 2:設定 SDK

您可透過 Google 的 Maven 存放區存取 Maps SDK for Android 程式庫。如要將 SDK 加入應用程式,請按照下列步驟操作:

  1. 在頂層 settings.gradle 檔案的 pluginManagement 區塊下方,加入 Gradle 外掛程式入口網站Google Maven 存放區,以及 Maven 中央存放區pluginManagement 區塊必須放在指令碼中的任何其他陳述式之前。
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    } 
  2. 在頂層 settings.gradle 檔案的 dependencyResolutionManagement 區塊下方,加入 Google Maven 存放區Maven 中央存放區
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
        }
    } 
  3. 在模組層級 build.gradle 檔案中,加入 Maps SDK for Android 的 Google Play 服務依附元件。
    dependencies {
        implementation 'com.google.android.gms:play-services-maps:18.0.2'
        // ...
    } 
  4. 在模組層級 build.gradle 檔案中,將 compileSdkminSdk 設為下列值:
    android {
        compileSdk 31
    
        defaultConfig {
            minSdk 19
            // ...
        }

步驟 3:將 API 金鑰加進專案

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

建議您使用 Secrets Gradle Plugin for Android 來簡化這項工作。如要安裝這個外掛程式並儲存 API 金鑰,請按照下列步驟操作:

  1. 在 Android Studio 中開啟專案層級的 build.gradle 檔案,然後將下列程式碼加進 buildscript 下方的 dependencies 元素。
    plugins {
        // ...
        id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
    }
  2. 接著,開啟模組層級的 build.gradle 檔案,然後將下列程式碼加進 plugins 元素。
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. 儲存檔案,然後使用 Gradle 同步處理專案
  4. 在專案層級目錄中開啟 local.properties 並新增下列程式碼,然後將 YOUR_API_KEY 替換成您的 API 金鑰。
    MAPS_API_KEY=YOUR_API_KEY
        
  5. 儲存檔案。
  6. 在您的 AndroidManifest.xml 檔案中,前往 com.google.android.geo.API_KEY 並按照以下方式更新 android:value attribute
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

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

步驟 4:更新應用程式資訊清單

本節說明需要新增至 AndroidManifest.xml 檔案的設定。

Google Play 服務版本號碼

application 元素中加入以下宣告。這會嵌入用來編譯應用程式的 Google Play 服務版本。

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

位置存取權

如果您的應用程式需要存取使用者的位置資訊,您就必須在 AndroidManifest.xml 檔案中要求位置存取權;可用的選擇包括 ACCESS_FINE_LOCATION (提供精確的使用者位置) 和 ACCESS_COARSE_LOCATION (較不精確)。詳情請參閱位置資料指南。

如要要求 ACCESS_FINE_LOCATION 權限,請將這段程式碼加進 manifest 元素:

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

外部儲存空間權限

如果您指定的是 8.3 以上版本的 Google Play 服務 SDK,就不需要 WRITE_EXTERNAL_STORAGE 權限。如果您指定的是舊版 Google Play 服務 SDK,則必須在 manifest 元素中要求 WRITE_EXTERNAL_STORAGE 權限。

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

Apache HTTP 舊版資料庫

如果您使用的是 com.google.android.gms:play-services-maps:16.0.0 以下版本,且您的應用程式指定 API 級別 28 (Android 9.0) 以上版本,就必須在 AndroidManifest.xml<application> 元素中加入以下宣告。如果不是,請略過這個宣告。

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

步驟 5:設定 Android 裝置

如要執行使用 Maps SDK for Android 的應用程式,請務必在採用 Android 4.0 以上版本且包含 Google API 的 Android 裝置或 Android Emulator 中,部署該應用程式。

  • 如要使用 Android 裝置,請按照在硬體裝置上執行應用程式一文的說明操作。
  • 如要使用 Android Emulator,您可以使用 Android Studio 隨附的 Android 虛擬裝置管理程式 (AVD Manager) 建立虛擬裝置並安裝模擬器。

後續步驟

專案設定完成後,您就可以新增地圖