設定 Android Studio 專案

如要將應用程式設為使用 Places SDK for Android，請按照下列步驟操作。所有使用 Places SDK for Android 的應用程式都必須符合這些要求。

步驟 1：設定 Android Studio

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

您可透過 Google 的 Maven 存放區存取 Places 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 檔案的 dependencies 區段中，將依附元件新增至 Places SDK for Android：

   dependencies {
       implementation 'com.google.android.libraries.places:places:3.3.0'
   }
   

4. 在模組層級 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，請按照下列步驟操作：

1. 在 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")
       }
   }
   

2. 開啟模組層級的 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")
   }

3. 儲存檔案，然後使用 Gradle 同步處理專案。
4. 在專案層級目錄中開啟 secrets.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}" />

7. 視需要編輯外掛程式的屬性，指定不同的 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 版本。

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey)

    // Create a new PlacesClient instance
    val placesClient = Places.createClient(this)
    

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(getApplicationContext(), apiKey);

    // Create a new PlacesClient instance
    PlacesClient placesClient = Places.createClient(this);
    

    // Initialize the SDK
    Places.initialize(applicationContext, apiKey)

    // Create a new PlacesClient instance
    val placesClient = Places.createClient(this)

      

    // 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) 建立虛擬裝置並安裝模擬器。

後續步驟