設定 Android Studio 專案

注意： Android 適用的 Places SDK 2.0.0 以上版本須使用 AndroidX。 自這個版本起，系統將不再支援舊版支援資料庫。如要保留相容性，請將專案遷移至使用 AndroidX。

如要設定應用程式使用 Places SDK for Android，請按照下列步驟操作。所有使用 Places SDK for Android 的應用程式都必須具備這些權限。

步驟 1：設定 Android Studio

本文件說明使用 Android Studio Hedgehog 和 Android Gradle 外掛程式 8.2 版的開發環境。

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

步驟 2：設定 SDK

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

1. 在頂層 settings.gradle.kts 檔案的 pluginManagement 區塊下方，加入 Gradle 外掛程式入口網站、Google Maven 存放區，以及 Maven 中央存放區。pluginManagement 區塊必須放在指令碼中的任何其他陳述式之前。

   pluginManagement {
       repositories {
           google()
           mavenCentral()
           gradlePluginPortal()
       }
   } 

2. 在頂層 settings.gradle.kts 檔案的 dependencyResolutionManagement 區塊下方，加入 Google Maven 存放區和 Maven 中央存放區：

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
       repositories {
           google()
           mavenCentral()
       }
   } 

3. 在模組層級 build.gradle.kts 檔案的 dependencies 區段中，新增 Places SDK for Android 的依附元件：

   注意： Places SDK for Android 3.5.0 版需要 kotlin-bom 1.8.0 以上版本。如要進一步瞭解 kotlin-bom 依附元件，請參閱「在遞移依附元件中使用最新版 kotlin-stdlib」。

   Groovy

   dependencies {
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
       implementation("com.google.android.libraries.places:places:3.5.0")
   }

   Kotlin

             dependencies {
   
       // Places and Maps SDKs
       implementation("com.google.android.libraries.places:places:6.0.2")
   }

4. 在模組層級 build.gradle.kts 檔案中，將 compileSdk 和 minSdk 設為下列值：
   注意：務必將 compileSdk 設為 34 以上，並將 minSdk 設為 23 以上。

   Groovy

   android {
       compileSdk 34
   
       defaultConfig {
           minSdk 23
           // ...
       }
   }

   Kotlin

   android {
       compileSdk = 34
   
       defaultConfig {
           minSdk = 23
           // ...
       }
   }

5. 在模組層級 build.gradle 檔案的 buildFeatures 部分，新增 BuildConfig 類別，該類別可用來存取此程序中稍後定義的中繼資料值：

   Groovy

   android {
     // ...
     buildFeatures {
       buildConfig true
       // ...
     }
   }

   Kotlin

   android {
     // ...
     buildFeatures {
       buildConfig = true
       // ...
     }
   }

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

本節說明如何儲存 API 金鑰，讓應用程式以安全的方式參照金鑰。API 金鑰不應登錄在版本管控系統中，因此建議將金鑰儲存在專案根目錄的 secrets.properties 檔案內，並將該檔案排除在版本管控之外。如要進一步瞭解 Gradle 屬性檔案，請參閱「Gradle 屬性檔案」。

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

如要安裝 Secrets Gradle Plugin for Android 並儲存 API 金鑰，請按照下列步驟操作：

1. 在 Android Studio 中開啟頂層的 build.gradle.kts 或 build.gradle 檔案， 然後將下列程式碼加進 plugins 區塊。

   Kotlin

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

   Groovy

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

2. 開啟模組層級的 build.gradle.kts 或 build.gradle 檔案，然後將下列程式碼加進 plugins 元素。

   Kotlin

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

   Groovy

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

3. 如果您使用 Android Studio，請使用 Gradle 同步處理專案。
4. 開啟頂層目錄中的 secrets.properties 檔案，並加入下列程式碼，然後將 YOUR_API_KEY 替換成您的 API 金鑰。請務必將 secrets.properties 新增至 .gitignore 檔案 (或從版本管控系統中排除)，以免將 API 金鑰登錄至版本管控系統。
   注意：如果 secrets.properties 檔案不存在，請在 local.properties 檔案所屬的資料夾中建立一個。

   PLACES_API_KEY=YOUR_API_KEY

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

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

   PLACES_API_KEY=DEFAULT_API_KEY

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

6. 在 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 root directory (the same folder as the root 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"
   }

   Groovy

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
   }

步驟 4：初始化 Places API 用戶端

如要在活動或片段中初始化 Places SDK for Android，請在呼叫 Places.initializeWithNewPlacesApiEnabled() 時傳遞 API 金鑰：

Kotlin

    // Define a variable to hold the Places API key.
    val apiKey = BuildConfig.PLACES_API_KEY

    // Log an error if apiKey is not set.
    if (apiKey.isEmpty() || apiKey == "DEFAULT_API_KEY") {
        Log.e("Places test", "No api key")
        finish()
        return
    }

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

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

Java

    // Define a variable to hold the Places API key.
    String apiKey = BuildConfig.PLACES_API_KEY;

    // Log an error if apiKey is not set.
    if (TextUtils.isEmpty(apiKey) || apiKey.equals("DEFAULT_API_KEY")) {
      Log.e("Places test", "No api key");
      finish();
      return;
    }

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

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

重要事項：請勿直接將 API 金鑰新增至應用程式程式碼。在正式環境中，建議使用安全機制管理 API 金鑰。

您現在可以開始使用 Places SDK for Android 了！

步驟 5：設定 Android 裝置

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

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

後續步驟

專案設定完成後，您可以探索範例應用程式。