设置

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

设置 Google Cloud 项目和 API 密钥

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

第 1 步

控制台

  1. 在 Google Cloud 控制台中，打开项目选择器页面，点击创建项目以开始创建新的 Cloud 项目。

    转到项目选择器页面

  2. 确保您的 Cloud 项目已启用结算功能。确认您的项目已启用结算功能。

    Google Cloud 提供免费试用。试用期将在 90 天后或者账号费用累积达到 300 美元时（以先到者为准）结束。您随时可以取消试用。如需了解详情，请参阅结算账号赠金和结算。

Cloud SDK

gcloud projects create "PROJECT"

您可以详细了解 Google Cloud SDK、Cloud SDK 安装和以下命令：

第 2 步

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

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

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

控制台

  1. 前往 Cloud 控制台中的“Maps API 库”页面，查看可启用的 Google Maps Platform API 和 SDK：

    前往“Maps API 库”页面

  2. 点击您想启用的 API 或 SDK。
    • 如果按钮显示启用，请点击此按钮以启用 API 或 SDK。
    • 如果按钮显示管理，则表示 API 或 SDK 已启用，您无需执行任何其他操作。
    • 点击任一按钮均可显示 API 或 SDK 的信息中心（点击停用按钮可从此项目中移除相应 API 或 SDK）。

Cloud SDK

以下命令会启用所有 Google 地图、路线和地点 API：

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"

详细了解 Google Cloud SDK、Cloud SDK 安装和以下命令：

使用以下命令启用 Environment API：

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

第 3 步

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

API 密钥是唯一标识符，用于对与您的项目相关联的请求进行身份验证，以便计算用量和执行结算。您必须至少有一个与您项目相关联的 API 密钥。

如需创建 API 密钥，请执行以下操作：

控制台

  1. 前往 Google Maps Platform > 凭据页面。

    前往“凭据”页面

  2. 在凭据页面上，依次点击创建凭据 > API 密钥。
    已创建的 API 密钥对话框会显示您新创建的 API 密钥。
  3. 点击关闭。
    新的 API 密钥即会列在凭据页面的 API 密钥下。
    （在生产环境中使用 API 密钥之前，请务必对 API 密钥设置限制。）

Cloud SDK

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

详细了解 Google Cloud SDK、Cloud 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 项目。

  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 目录中。 - 在“版本”部分，添加 SDK 和 Secrets Gradle 插件的版本：

    maps3dSdk = "0.0.1" # Update this value to match the SDK version to include
secretsGradlePlugin = "2.0.1"

    -   In the library section, add the SDK library:

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

    -   In the plugin section, add the Secrets Gradle plugin:

    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
}

    -   In the `dependencies` block, add the SDK:

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

    -   At the end of the file, outside of the `android` and `dependencies`
    blocks, add the secrets configuration:

    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
``` Note: Make sure you
    replace `YOUR_API_KEY_HERE` with the API key that you configured for use
with the Maps 3D SDK for Android.

  2. 创建 local.defaults.properties 文件： - 在应用模块根目录中，创建一个名为 secrets.properties 的新文件。 - 向文件添加默认 API 密钥或占位符 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 文件中的密钥。

后续步骤

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