本頁面由 Cloud Translation API 翻譯而成。

設定 Android Studio 專案

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

步驟 1：設定 Android Studio

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

步驟 2：設定 SDK

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

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

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

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

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

注意： Android 版 Places SDK 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:4.1.0")
}
```

在模組層級的 build.gradle.kts 檔案中，將 compileSdk 和 minSdk 設為下列值：

注意：compileSdk 必須設為 34 以上，minSdk 則設為 23 以上。

Groovy

android {
    compileSdk 34

    defaultConfig {
        minSdk 23
        // ...
    }
}

Kotlin

android {
    compileSdk = 34

    defaultConfig {
        minSdk = 23
        // ...
    }
}

在模組層級 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.kts 或 build.gradle 檔案，然後將下列程式碼加進 buildscript 下方的 dependencies 元素。

Kotlin

buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}

Groovy

buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}

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

Kotlin

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

Groovy

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

在模組層級的 build.gradle.kts 或 build.gradle 檔案中，確認 targetSdk 和 compileSdk 已設為 34。
使用 Gradle 同步處理專案。
開啟頂層目錄中的 secrets.properties 檔案，並加入下列程式碼，然後將 YOUR_API_KEY 替換成您的 API 金鑰。secrets.properties 不會登錄在版本管控系統中，因此請將金鑰儲存至該檔案。
注意： 如果 secrets.properties 檔案不存在，請在 local.properties 檔案所屬的資料夾中建立一個。
```
PLACES_API_KEY=YOUR_API_KEY
```
在頂層目錄 (與 secrets.properties 檔案相同的資料夾) 中建立 local.defaults.properties 檔案，然後加入下列程式碼。

注意：輸入的程式碼必須與下列內容完全一致。請勿將 DEFAULT_API_KEY 替換成您的 API 金鑰。
```
PLACES_API_KEY=DEFAULT_API_KEY
```
如果找不到 secrets.properties 檔案，這個檔案便可做為 API 金鑰的備份位置，以確保建置程序不會失敗。如果您從略過 secrets.properties 的版本管控系統複製應用程式，且尚未在本機建立 secrets.properties 檔案來提供 API 金鑰，就可能會發生這種情況。

在 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 same folder as the 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 same folder as the 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。您必須先決定要使用哪個版本的 SDK：Places SDK for Android 或 Places SDK for Android (新版)。如要進一步瞭解產品版本，請參閱「選擇 SDK 版本」。

以下範例說明如何為這兩個版本初始化 SDK。

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);

Places SDK for Android

在呼叫 Places.initialize() 時傳遞 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.initialize(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.initialize(getApplicationContext(), apiKey);

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

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

步驟 5：設定 Android 裝置

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

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

後續步驟

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