设置 Android Studio 项目

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

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

第 1 步:设置 Android Studio

本文档介绍的是使用 Android Studio HedgehogAndroid 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.ktsbuild.gradle 文件中,添加 Google Play 服务依赖项 Maps SDK for Android

    Kotlin

    dependencies {
    
        // Maps SDK for Android
        implementation("com.google.android.gms:play-services-maps:19.0.0")
    }

    Groovy

    dependencies {
    
        // Maps SDK for Android
        implementation "com.google.android.gms:play-services-maps:19.0.0"
    }
  4. 在您的模块级 build.gradle.ktsbuild.gradle 文件中, 将 compileSdkminSdk 设置为以下值:

    Kotlin

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

    Groovy

    android {
        compileSdk 34
    
        defaultConfig {
            minSdk 21
            // ...
        }
    }
  5. 在模块级 build.gradle.ktsbuildFeatures 部分中 或 build.gradle 文件中,请添加 BuildConfig 类,该类可用于 访问此过程后面部分定义的元数据值:

    Kotlin

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

    Groovy

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

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

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

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

如需在 Google 地图项目中安装 Android 版 Secret Gradle 插件,请执行以下操作:

  1. 在 Android Studio 中,打开顶级 build.gradle.ktsbuild.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"
        }
    }
    
  2. 打开模块级 build.gradle.ktsbuild.gradle 文件并添加 将以下代码添加到 plugins 元素中。

    Kotlin

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

    Groovy

    plugins {
        // ...
        id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
    }
  3. 在模块级 build.gradle.ktsbuild.gradle 文件中,确保 已设置 targetSdkcompileSdk 到 34。
  4. 保存文件并将项目与 Gradle 同步
  5. 在顶级目录中打开 secrets.properties 文件,然后添加以下代码。将 YOUR_API_KEY 替换为您的 API 密钥。secrets.properties 不会签入版本控制系统,因此请将您的密钥存储在此文件中。
    MAPS_API_KEY=YOUR_API_KEY
  6. 保存文件。
  7. 在顶级目录(即 secrets.properties 文件所在的文件夹)中创建 local.defaults.properties 文件,然后添加以下代码。

    MAPS_API_KEY=DEFAULT_API_KEY

    此文件的作用是为 API 密钥提供备用位置,以免在找不到 secrets.properties 文件的情况下构建失败。如果您是从省略 secrets.properties 的版本控制系统中克隆应用,而您还没有在本地创建 secrets.properties 文件来提供 API 密钥,就可能会出现构建失败。

  8. 保存文件。
  9. AndroidManifest.xml 文件中,定位到 com.google.android.geo.API_KEY 并更新 android:value attribute。如果 <meta-data> 标记不存在,请创建该标记作为 <application> 标记。
    <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 会抛出异常。

  10. 在 Android Studio 中,打开模块级 build.gradle.ktsbuild.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 步:更新应用清单

本部分介绍了要添加到 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 设备或 Android 基于 Android 5.0 或更高版本且包含以下内容的模拟器: Google API。

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

第 6 步:(可选)检查是否已安装 Play 服务

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

后续步骤

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