设置 Android Studio 项目

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

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

第 1 步：设置 Android Studio

必须使用 Android Studio Arctic Fox 或更高版本。如果您尚未安装，请下载并安装。
确保您在 Android Studio 中使用的是 Android Gradle 插件 7.0 或更高版本。

第 2 步：设置 SDK

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

在顶级 settings.gradle 文件的 pluginManagement 代码块下，添加 Gradle 插件门户、Google Maven 代码库和 Maven 中央代码库。pluginManagement 代码块必须位于脚本中的任何其他语句之前。
```
pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
} 
```

在顶级 settings.gradle 文件的 dependencyResolutionManagement 代码块下，添加 Google 的 Maven 代码库和 Maven 中央代码库：

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

在模块级 build.gradle 文件中，为 Maps SDK for Android 添加 Google Play 服务依赖项。

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.0'
    // ...
}

在模块级 build.gradle 文件中，将 compileSdk 和 minSdk 设置为以下值：
注意：确保将 compileSdk 设置为 31 或更高版本，并将 minSdk 设置为 19 或更高版本。
```
android {
    compileSdk 31

    defaultConfig {
        minSdk 19
        // ...
    }
```

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

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

为了简化此任务，我们建议您使用 Android 版 Secrets Gradle 插件。如需安装此插件并存储您的 API 密钥，请执行以下操作：

在 Android Studio 中，打开项目级 build.gradle 文件，并将以下代码添加到 buildscript 下的 dependencies 元素中。
```
plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
```
接下来，打开模块级 build.gradle 文件，并将以下代码添加到 plugins 元素中。
```
id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
    
```
保存文件并将项目与 Gradle 同步。
在项目级目录中打开 local.properties，然后添加以下代码。将 YOUR_API_KEY 替换为您的 API 密钥。
```
MAPS_API_KEY=YOUR_API_KEY
    
```
保存文件。
在 AndroidManifest.xml 文件中，定位到 com.google.android.geo.API_KEY 并按如下所示更新 android:value attribute：
```
<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 4.0 或更高版本且包含 Google API 的 Android 设备或 Android 模拟器。

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

后续步骤

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