Настройка

На этой странице описано, что нужно сделать, чтобы начать разработку с помощью Maps 3D SDK для Android. Для этого нужно настроить проект Google Cloud и API для использования с SDK, а затем настроить проект Android Studio. Выполните эти действия, прежде чем добавить первую 3D-карту в приложение.

Требования

Чтобы использовать Maps 3D SDK для Android, ваш проект и целевые устройства должны соответствовать следующим требованиям:

• Минимальный уровень API: Android API 24 (Android 7.0) или выше. Приложение должно быть предназначено для minSdk версии 24 или выше.
• Сервисы Google Play. Maps 3D SDK для Android зависит от сервисов Google Play. На целевых устройствах (и эмуляторах с API Google) должны быть установлены сервисы Google Play.

Как настроить проект Google Cloud и ключ API

Чтобы начать разработку с помощью Maps 3D SDK для Android, вам нужно настроить проект Google Cloud и ключ API для использования с Maps 3D SDK для Android, выполнив следующие действия:

Шаг 1. Настройте проект

gcloud projects create "PROJECT"

Шаг 2. Включите API или SDK

Для работы с платформой Google Карт вам потребуется включить API и SDK, которые будут использоваться в проекте.

Для некоторых проектов требуется включить несколько API и SDK. Если вы не знаете, какие продукты вам нужны, воспользуйтесь инструментом выбора API или прочитайте документацию по работе с соответствующими 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. Чтобы создать ключ или добавить API или SDK к существующему ключу, следуйте инструкциям ниже.

Чтобы включить SDK, перейдите на страницу Maps 3D SDK для Android в консоли Google Cloud. Подробная информация о том, как выполнить эти действия, приведена в статье Начало работы с платформой Google Карт.

Настройка проекта Android Studio

В этом разделе объясняется, как создать и настроить проект Android Studio для использования с Maps 3D SDK для Android.

Часть 1. Настройка проекта и конфигурации Gradle

1. Создайте проект Android Studio, используя шаблон Empty Views Activity (Пустое действие представлений). В конфигурации проекта установите для параметра Minimum SDK (Минимальная версия 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 добавьте зависимость сервисов Google Play для Maps 3D SDK для Android:

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

   • В конце файла, за пределами блоков android и dependencies, добавьте конфигурацию секретов:

   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 для Android, вы можете добавить 3D-карту в приложение.