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

設定 Android Studio 專案

如要將應用程式設為使用 Places SDK for Android，請按照下列步驟操作： 100 萬步的訓練凡是使用 Places SDK for Android 的應用程式，都必須具備這些屬性。

步驟 1：設定 Android Studio

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

步驟 2：設定 SDK

Places SDK for Android 程式庫是透過 Google 的 Maven 存放區。如要將 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()
    }
}

在「dependencies」中位於模組層級 build.gradle 檔案中的區段，請新增依附元件 Places SDK for Android 的部分功能：

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

Groovy

dependencies {
    // If updating kotlin-bom version number above, also edit project-level build.gradle definition of $kotlin_version variable
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
    implementation 'com.google.android.libraries.places:places:3.3.0'
}

Kotlin

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

在模組層級 build.gradle 檔案中設定 compileSdk 並將 minSdk 設為下列值：

注意：請確認 compileSdk 為設為 34 以上，且 minSdk 設為 21 以上。

Groovy

android {
    compileSdk 34

    defaultConfig {
        minSdk 21
        // ...
    }
}

Kotlin

android {
    compileSdk = 34

    defaultConfig {
        minSdk = 21
        // ...
    }
}

在模組層級 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"

    // 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.*"
}

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"

    // 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：初始化 Places API 用戶端

在活動或片段中初始化 Places SDK for Android。您必須先決定要使用哪個 SDK 版本：Places SDK for Android Places SDK for Android (新版)。如要進一步瞭解產品版本請參閱「選擇 SDK 版本」一文。

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

Places SDK for Android (新推出)

呼叫時傳遞 API 金鑰 Places.initializeWithNewPlacesApiEnabled():

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

呼叫時傳遞 API 金鑰 Places.initialize():

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 裝置或 Android 以 Android 5.0 以上版本為基礎，且包含 Google API

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

後續步驟

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