本頁說明如何將 Android Studio 專案設為使用 Maps SDK for Android,但不採用快速入門導覽課程中詳述的 Google 地圖範本。
Google 地圖範本會自動設定基本地圖,並加進新的 Android Studio 專案,您也可以將地圖新增至使用其他 Android Studio 範本的 Android 專案,但需要手動設定專案,然後再新增地圖。
步驟 1:設定 Android Studio
本文件說明使用 Android Studio Hedgehog 和 Android Gradle 外掛程式 8.2 版的開發環境。
步驟 2:設定 SDK
您可透過 Google 的 Maven 存放區存取 Maps SDK for Android 程式庫。如要將 SDK 加入應用程式,請按照下列步驟操作:
- 在頂層
settings.gradle
檔案的pluginManagement
區塊下方,加入 Gradle 外掛程式入口網站、Google Maven 存放區,以及 Maven 中央存放區。pluginManagement
區塊必須放在指令碼中的任何其他陳述式之前。pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- 在頂層
settings.gradle
檔案的dependencyResolutionManagement
區塊下方,加入 Google Maven 存放區和 Maven 中央存放區:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- 在模組層級
build.gradle
檔案中,加入 Maps SDK for Android 的 Google Play 服務依附元件。Groovy
dependencies { // Maps SDK for Android implementation 'com.google.android.gms:play-services-maps:18.2.0' }
Kotlin
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:18.2.0") }
- 在模組層級
build.gradle
檔案中,將compileSdk
和minSdk
設為下列值:Groovy
android { compileSdk 34 defaultConfig { minSdk 19 // ... } }
Kotlin
android { compileSdk = 34 defaultConfig { minSdk = 19 // ... } }
- 在模組層級
build.gradle
檔案的buildFeatures
部分,新增BuildConfig
類別,該類別可用來存取此程序中稍後定義的中繼資料值:Groovy
android { // ... buildFeatures { buildConfig true // ... } }
Kotlin
android { // ... buildFeatures { buildConfig = true // ... } }
步驟 3:將 API 金鑰加到專案
本節將說明如何儲存 API 金鑰,讓應用程式以安全的方式參照金鑰。API 金鑰不應該登錄在版本管控系統中;我們建議將金鑰儲存在位於專案根目錄的 secrets.properties
檔案內。如要進一步瞭解 secrets.properties
檔案,請參閱這篇文章中關於 Gradle 屬性檔案的說明。
建議您使用 Secrets Gradle Plugin for Android 來簡化這項工作。
如要在 Google 地圖專案中安裝 Secrets Gradle Plugin for Android,請按照下列步驟操作:
-
在 Android Studio 中開啟頂層的
build.gradle
或build.gradle.kts
檔案, 然後將下列程式碼加進buildscript
下方的dependencies
元素。Groovy
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
-
開啟模組層級的
build.gradle
檔案,然後將下列程式碼加進plugins
元素。Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
Kotlin
plugins { id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
- 在模組層級的
build.gradle
檔案中,確認targetSdk
和compileSdk
已設為 34。 - 儲存檔案,然後使用 Gradle 同步處理專案。
-
開啟頂層目錄中的
secrets.properties
檔案,並加入下列程式碼,然後將YOUR_API_KEY
替換成您的 API 金鑰。secrets.properties
不會登錄在版本管控系統中,因此請將金鑰儲存至該檔案。MAPS_API_KEY=YOUR_API_KEY
- 儲存檔案。
-
在頂層目錄 (與
secrets.properties
檔案相同的資料夾) 中建立local.defaults.properties
檔案,然後加入下列程式碼。MAPS_API_KEY=DEFAULT_API_KEY
如果找不到
secrets.properties
檔案,這個檔案便可做為 API 金鑰的備份位置,以確保建置程序不會失敗。如果您從略過secrets.properties
的版本管控系統複製應用程式,且尚未在本機建立secrets.properties
檔案來提供 API 金鑰,就可能會發生這種情況。 - 儲存檔案。
-
找到
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}" />
Note:
com.google.android.geo.API_KEY
is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the namecom.google.android.maps.v2.API_KEY
. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception. -
In Android Studio, open your module-level
build.gradle
orbuild.gradle.kts
file and edit thesecrets
property. If thesecrets
property does not exist, add it.Edit the properties of the plugin to set
propertiesFileName
tosecrets.properties
, setdefaultPropertiesFileName
tolocal.defaults.properties
, and set any other properties.Groovy
secrets { // Optionally specify a different file name 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" // 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.*" }
Kotlin
secrets { // Optionally specify a different file name 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" // 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.*" }
步驟 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 模擬器。
- 如要使用 Android 裝置,請按照在硬體裝置上執行應用程式一文的說明操作。
- 如要使用 Android 模擬器,您可以使用 Android Studio 隨附的 Android 虛擬裝置管理工具 (AVD Manager) 建立虛擬裝置並安裝模擬器。
(選擇性) 步驟 6:檢查是否已安裝 Play 服務
Maps SDK for Android 要求用來部署應用程式的裝置必須安裝 Google Play 服務。您可以使用 Google 提供的方法,從應用程式呼叫進行檢查。詳情請參閱「檢查 Google Play 服務是否已安裝」一文。
後續步驟
專案設定完成後,您就可以新增地圖。
除非另有註明,否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權,程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間:2024-05-09 (世界標準時間)。
[] [] { "last_modified": "上次更新時間:2024-05-09 (世界標準時間)。", "state": "" }