如要將應用程式設為使用 Places SDK for Android,請按照下列步驟操作。所有使用 Places SDK for Android 的應用程式都必須符合這些要求。
步驟 1:設定 Android Studio
- 必須使用 Android Studio Arctic Fox 或更新版本。如果您尚未下載並安裝,請先完成此步驟。
- 確認您在 Android Studio 中使用的是 Android Gradle 外掛程式 7.0 以上版本。
步驟 2:設定 SDK
您可透過 Google 的 Maven 存放區存取 Places 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
檔案的dependencies
區段中,將依附元件新增至 Places SDK for Android:dependencies { implementation 'com.google.android.libraries.places:places:3.3.0' }
- 在模組層級
build.gradle
檔案中,將compileSdk
和minSdk
設為下列值:android { compileSdk 31 defaultConfig { minSdk 21 // ... }
步驟 3:將 API 金鑰加進專案
本節將說明如何儲存 API 金鑰,讓應用程式以安全的方式參照金鑰。API 金鑰不應該登錄在版本管控系統中;我們建議將金鑰儲存在位於專案根目錄的 secrets.properties
檔案內。如要進一步瞭解 secrets.properties
檔案,請參閱這篇文章中關於 Gradle 屬性檔案的說明。
建議您使用 Secrets Gradle Plugin for Android 來簡化這項工作。
如要在 Google 地圖專案中安裝 Secrets Gradle Plugin for Android,請按照下列步驟操作:
- 在 Android Studio 中開啟專案層級的
build.gradle
檔案,然後將下列程式碼加進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") }
- 儲存檔案,然後使用 Gradle 同步處理專案。
- 在專案層級目錄中開啟
secrets.properties
並新增下列程式碼,然後將YOUR_API_KEY
替換成您的 API 金鑰。MAPS_API_KEY=YOUR_API_KEY
- 儲存檔案。
- 在您的
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}" />
視需要編輯外掛程式的屬性,指定不同的 Secrets 檔案或其他屬性。 在 Android Studio 中開啟專案層級的
build.gradle
檔案,然後編輯secrets
屬性: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.*" }
注意事項:如上所示,API 金鑰的建議中繼資料名稱為 com.google.android.geo.API_KEY
。具備這個名稱的金鑰可用來驗證 Android 平台上的多個 Google 地圖相關 API,包括 Places SDK for Android。為了兼顧回溯相容性,API 也支援 com.google.android.maps.v2.API_KEY
這個名稱。此舊版名稱僅允許對 Android Maps API 第 2 版進行驗證。應用程式只能指定這兩種 API 金鑰中繼資料名稱的其中一個;如果同時指定兩者,API 會擲回例外狀況。
步驟 4:初始化 Places API 用戶端
在活動或片段中初始化 Places SDK for Android。您必須先決定要使用的 SDK 版本:Places SDK for Android 或 Places SDK for Android (新版)。如要進一步瞭解產品版本,請參閱選擇 SDK 版本。
以下範例說明如何初始化這兩個版本的 SDK。Places SDK for Android (新推出)
在呼叫 Places.initializeWithNewPlacesApiEnabled()
時傳遞 API 金鑰:
Kotlin
// Initialize the SDK Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey) // Create a new PlacesClient instance val placesClient = Places.createClient(this)
Java
// Initialize the SDK Places.initializeWithNewPlacesApiEnabled(getApplicationContext(), apiKey); // Create a new PlacesClient instance PlacesClient placesClient = Places.createClient(this);
Places SDK for Android
在呼叫 Places.initialize()
時傳遞 API 金鑰:
Kotlin
// Initialize the SDK Places.initialize(applicationContext, apiKey) // Create a new PlacesClient instance val placesClient = Places.createClient(this)
Java
// Initialize the SDK Places.initialize(getApplicationContext(), apiKey); // Create a new PlacesClient instance PlacesClient placesClient = Places.createClient(this);
您現在可以開始使用 Places SDK for Android 了!
步驟 5:設定 Android 裝置
如要執行使用 Places SDK for Android 的應用程式,請務必將該應用程式部署至採用 Android 4.0 以上版本且包含 Google API 的 Android 裝置或 Android 模擬器。
- 如要使用 Android 裝置,請按照在硬體裝置上執行應用程式一文的說明操作。
- 如要使用 Android 模擬器,您可以使用 Android Studio 隨附的 Android 虛擬裝置管理工具 (AVD Manager) 建立虛擬裝置並安裝模擬器。