设置 Android Studio 项目

本页面介绍了如何在不使用快速入门中详细介绍的 Google 地图模板的情况下，将 Android Studio 项目配置为使用 Maps SDK for Android。

Google 地图模板会自动配置基本地图，并将此类地图添加到新的 Android Studio 项目。不过，您也可以向使用其他 Android Studio 模板的 Android 项目添加地图。为此，您需要先手动配置项目，然后再添加地图。

第 1 步：设置 Android Studio

本文档介绍的是使用 Android Studio Hedgehog 和 Android Gradle 插件 8.2 版的开发环境。

第 2 步：设置 SDK

您可以通过 Google 的 Maven 制品库获取 Maps SDK for Android 库。要将 SDK 添加到您的应用中，请执行以下操作：

  1. 在顶级 settings.gradle.kts 文件的 pluginManagement 代码块下，添加 Gradle 插件门户、Google 的 Maven 制品库和 Maven 中央存储库。pluginManagement 代码块必须位于脚本中的任何其他语句之前。 
    pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
  2. 在顶级 settings.gradle.kts 文件的 dependencyResolutionManagement 代码块下，添加 Google 的 Maven 代码库和 Maven 中央代码库： 
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
  3. 在模块级 build.gradle.kts 或 build.gradle 文件中，为 Maps SDK for Android 添加 Google Play 服务依赖项。

    Kotlin

    dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

    Groovy

    dependencies {

    // Maps SDK for Android
    implementation "com.google.android.gms:play-services-maps:19.0.0"
}
  4. 在模块级 build.gradle.kts 或 build.gradle 文件中，将 compileSdk 和 minSdk 设置为以下值：

    Kotlin

    android {
    compileSdk = 34

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

    Groovy

    android {
    compileSdk 34

    defaultConfig {
        minSdk 21
        // ...
    }
}
  5. 在模块级 build.gradle.kts 或 build.gradle 文件的 buildFeatures 部分中，添加 BuildConfig 类；您可以使用该类访问此过程中稍后定义的元数据值：

    Kotlin

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

    Groovy

    android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}
  6. 在 libs.versions.toml 文件中，添加以下内容： 
    [versions]
play-services-maps = "19.2.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

第 3 步：将您的 API 密钥添加到项目中

本部分介绍了如何存储 API 密钥，以便您的应用可以安全引用该密钥。您不应将 API 密钥签入版本控制系统，建议将其存储在项目根目录下的 secrets.properties 文件中。如需详细了解 secrets.properties 文件，请参阅 Gradle 属性文件。

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

如需安装 Android 版 Secrets Gradle 插件并存储您的 API 密钥，请执行以下操作：

  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.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    Kotlin

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. 如果您使用 Android Studio，请将项目与 Gradle 同步。
  4. 在项目级目录中打开 local.properties，然后添加以下代码。将 YOUR_API_KEY 替换为您的 API 密钥。 
    MAPS_API_KEY=YOUR_API_KEY
  5. 在 AndroidManifest.xml 文件中，定位到 com.google.android.geo.API_KEY 并按如下所示更新 android:value 属性： 
    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

    注意：建议使用 com.google.android.geo.API_KEY 作为 API 密钥的元数据名称。您可以使用采用该名称的密钥接受 Android 平台上多个基于 Google 地图的 API（包括 Maps SDK for Android）的身份验证。为了实现向后兼容性，该 API 还支持名称 com.google.android.maps.v2.API_KEY。但使用该旧名称时，密钥只能接受 Android Maps API v2 的身份验证。应用只能指定其中一个 API 密钥元数据名称。如果两个都指定，API 会抛出异常。

第 4 步：更新应用清单

本部分介绍了要添加到 AndroidManifest.xml 文件中的设置。

Google Play 服务版本号

在 application 元素中添加以下声明。该操作会嵌入编译应用时所用 Google Play 服务的版本。

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

位置信息权限

如果您的应用需要访问用户的位置信息，那么您就需要在 AndroidManifest.xml 文件中请求位置信息权限。您可以选择请求 ACCESS_FINE_LOCATION（可提供精确的设备位置信息），也可以选择请求 ACCESS_COARSE_LOCATION（提供的位置信息不太精确）。如需了解详情，请参阅位置数据指南。

如要请求 ACCESS_FINE_LOCATION 权限，请将以下代码添加到 manifest 元素中：

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

外部存储权限

如果您的目标平台是 8.3 版或更高版本的 Google Play 服务 SDK，则您不需要 WRITE_EXTERNAL_STORAGE 权限。如果目标平台是较低版本的 Google Play 服务 SDK，则必须在 manifest 元素中请求 WRITE_EXTERNAL_STORAGE 权限。

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Apache HTTP 旧版库

如果您使用的是 com.google.android.gms:play-services-maps:16.0.0 或更低版本，并且您的应用以 API 级别 28 (Android 9.0) 或更高级别为目标平台，那么您必须在 AndroidManifest.xml 的 <application> 元素中添加以下声明。否则，请跳过添加声明这一步。

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

第 5 步：设置 Android 设备

如要运行使用 Maps SDK for Android 的应用，您必须将其部署到搭载 Android 5.0 或更高版本且包含 Google API 的 Android 设备或 Android 模拟器。

  • 如要使用 Android 设备，请按照在硬件设备上运行应用一文中的说明操作。
  • 如要使用 Android 模拟器，您可以使用 Android Studio 随附的 Android 虚拟设备 (AVD) 管理器来创建虚拟设备并安装模拟器。

第 6 步：（可选）检查是否已安装 Play 服务

若要使用 Maps SDK for Android，您部署应用的设备上必须已安装 Google Play 服务。您可以在应用中调用 Google 提供的一种方法，对此进行检查。 如需了解详情，请参阅检查是否已安装 Google Play 服务。

后续步骤

配置完项目后，您就可以添加地图了。