设置 Android Studio 项目

注意： Places SDK for Android 的 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's 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. 在 dependencies 文件的 模块 级 build.gradle.kts 部分中，添加对 Places SDK for Android 的依赖项：

   注意： Places SDK for Android 3.5.0 版需要 kotlin-bom 1.8.0 或更高版本。如需详细了解 kotlin-bom 依赖项，请参阅 Usage of the latest kotlin-stdlib version in transitive dependencies。

   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 属性文件。

为了简化此任务，建议您使用 Android 版 Secrets Gradle 插件。

如需安装 Android 版 Secrets Gradle 插件并存储您的 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

   此文件的作用是为 API 密钥提供备用位置 ，以免在找不到 secrets.properties 文件的情况下构建 失败。如果您是从省略 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 客户端

如需在 activity 或 fragment 中初始化 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 APIs 的 Android 设备或 Android 模拟器。

• 如要使用 Android 设备，请按照在 硬件设备上运行应用一文中的说明操作。
• 如要使用 Android 模拟器，您可以使用 Android Studio 随附的设备管理器来创建虚拟设备并安装模拟器。
  注意：如果您选择使用 Android 模拟器，请务必选择带有 Play 图标（ ， 显示在 Play 商店 列下方）的设备配置文件。此图标表明 相应设备的配置完全 CTS 规范，并且可以使用包含 Play 商店应用的系统映像。

后续步骤

配置完项目后，您就可以探索 示例应用了。