设置

本页面介绍了开始使用 Maps 3D SDK for Android 进行构建之前需要完成的设置。设置过程包括：配置 Google Cloud 项目和 API 以便与 SDK 搭配使用，然后设置 Android Studio 项目。在向应用添加第一个 3D 地图之前，请先完成以下步骤。

前提条件

如需使用 Maps 3D SDK for Android，您的项目和目标设备必须满足以下要求：

• 最低 API 级别：Android API 级别 24 (Android 7.0) 或更高级别。您的应用必须以 24 或更高级别的 minSdk 为目标平台。
• Google Play 服务：Maps 3D SDK for Android 依赖于 Google Play 服务。目标设备（以及具有 Google API 的模拟器）必须安装 Google Play 服务。

设置 Google Cloud 项目和 API 密钥

在开始使用 Maps 3D SDK for Android 进行构建之前，您需要设置一个 Google Cloud 云项目和 API 密钥，以便与 Maps 3D SDK for Android 搭配使用。为此，请完成以下步骤：

第 1 步：设置项目

gcloud projects create "PROJECT"

第 2 步：启用 API 或 SDK

如要使用 Google Maps Platform，您必须启用计划用于项目的 API 或 SDK。

请注意，有些集成需要您启用多个 API/SDK。如果您不确定要启用哪些 API 或 SDK，请尝试使用功能探索器，或参阅想使用的 API/SDK 对应的文档。

如需启用一个或多个 API/SDK，请执行以下操作：

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-backend.googleapis.com"

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.googleapis.com"

第 3 步：获取 API 密钥

此步骤仅包含 API 密钥的创建流程。如要在生产环境中使用 API 密钥，强烈建议您为相应密钥设置限制。如需了解详情，请参阅相应产品的使用 API 密钥页面。

API 密钥是唯一标识符，用于对与您的项目相关联的请求进行身份验证，以便您使用相关产品和执行结算。您必须至少有一个与您项目相关联的 API 密钥。 如需创建新密钥或向现有密钥添加 API 或 SDK，请按照以下说明操作。

如需启用该 SDK，请参阅 Google Cloud 控制台中的 Maps 3D SDK for Android 页面。如需详细了解如何完成这些步骤，请参阅 Google Maps Platform 使用入门。

设置 Android Studio 项目

本部分介绍了如何创建和配置 Android Studio 项目，以便与 Maps 3D SDK for Android 搭配使用。

第 1 部分：设置项目和 Gradle 配置

1. 使用 Empty Views Activity 模板创建一个新的 Android Studio 项目。在项目配置中，将 Minimum SDK 设置为 API 24 或更高级别。

2. 如果您使用 Git 进行源代码控制，请修改项目 .gitignore 文件，以防止将密钥文件提交到版本控制系统：

   • 在项目的根目录中，打开 .gitignore 文件。
   • 添加以下代码行：

   secrets.properties
   

3. 更新项目级 build.gradle.kts 文件：

   • 在项目的根目录中，打开 build.gradle.kts 文件。
   • 在 plugins 代码块中，添加 Secrets Gradle 插件：

   plugins {
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
   }
   

4. 更新 gradle/libs.versions.toml 文件。

   • 打开 gradle/libs.versions.toml 文件，该文件通常位于项目根目录中的 gradle 目录下。
   • 在 [versions] 部分中，添加 SDK 和 Secrets Gradle 插件的版本：

   # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
   maps3dSdk = "16.0.1"
   # See https://github.com/google/secrets-gradle-plugin/releases for available releases
   secretsGradlePlugin = "2.0.1"
   

   • 在 [library] 部分中，添加 SDK 库：

   play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
   

   • 在 [plugins] 部分中，添加 Secrets Gradle 插件：

   secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }
   

5. 更新模块级 app/build.gradle.kts 文件：

   • 打开模块级 build.gradle.kts 文件，该文件通常位于 app 目录中。
   • 在文件顶部，将 Secrets Gradle 插件添加到 plugins 块中：

   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.secrets.gradle.plugin) // Add this line
   }
   

   • 在 dependencies 代码块中，为 Maps 3D SDK for Android 添加 Google Play 服务依赖项：

   dependencies {
       // ... other dependencies
       implementation(libs.play.services.maps3d) // Add this line
   }
   

   • 在文件末尾，在 android 和 dependencies 代码块之外，添加 Secret 配置：

   secrets {
       // Optionally specify a different filename containing your secrets.
       // The plugin defaults to "local.properties"
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
   

第 2 部分：将 API 密钥添加到项目中

1. 创建 secrets.properties 文件：

   • 在应用模块根目录（通常为 app 目录）中，创建一个名为 secrets.properties 的新文件。
   • 将您的 API 密钥添加到该文件中：

   MAPS3D_API_KEY=YOUR_API_KEY_HERE
   

2. 创建 local.defaults.properties 文件： - 在应用模块根目录中，创建一个名为 local.defaults.properties 的新文件。 - 向该文件添加默认或占位 API 密钥。此文件可以签入版本控制：

   MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
   

第 3 部分：更新 AndroidManifest.xml 文件

1. 打开 app/src/main/AndroidManifest.xml 文件。

2. 在 <application> 标记内、<activity> 标记前，添加以下 <meta-data> 元素以声明您的 API 密钥：

   <application
       ...>
   
       <meta-data
           android:name="com.google.android.geo.maps3d.API_KEY"
           android:value="${MAPS3D_API_KEY}" />
   
       <activity
           ...>
       </activity>
   </application>
   

   在构建过程中，Secrets Gradle 插件会将 ${MAPS3D_API_KEY} 占位符替换为 secrets.properties 文件中的密钥。

程序化视图初始化（可选）

如果您希望以编程方式（而非在 XML 布局中）初始化地图视图，请使用 Map3DInitConfig。

import com.google.android.gms.maps3d.Map3DInitConfig
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.model.Map3DMode

// Set configuration options using the factory method
val config = Map3DInitConfig.create(
    mapMode = Map3DMode.HYBRID,
    centerLat = 38.544012,
    centerLng = -107.670428
)

val map3DView = Map3DView(context, config)

后续步骤

现在，您已经设置好 Google Cloud 云项目、API 密钥和 Android Studio 项目，可以与 Maps 3D SDK for Android 搭配使用，接下来可以向应用添加 3D 地图。