Настройка

На этой странице описано, как начать работу с 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

Консоль

1. Перейдите на страницу выбора проекта в консоли Google Cloud и нажмите Create Project (Создать проект).

   Перейти на страницу выбора проекта

2. Убедитесь, что для проекта Google Cloud включены платежные функции.

   Мы предлагаем бесплатный пробный период для использования Google Cloud. Он длится 90 дней или пока сумма расходов не достигнет 300 долл. США в зависимости от того, что произойдет раньше. Отказаться от предложения можно в любое время. Ознакомьтесь с информацией о бонусах в платежных аккаунтах и об оплате.

Cloud SDK

gcloud projects create "PROJECT"

Прочитайте статьи о Google Cloud SDK, установке Cloud SDK и следующих командах:

• gcloud projects create

Примечание. Если вы не планируете использовать ресурсы, которые появятся в результате выполнения этого упражнения, не выбирайте существующий проект, а создайте новый. После завершения упражнения вы сможете удалить проект, и все ресурсы, связанные с ним, также будут удалены.

Шаг 2

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

Для некоторых проектов требуется включить несколько API и SDK. Если вы не знаете, какие продукты вам нужны, воспользуйтесь инструментом выбора API или прочитайте документацию по работе с соответствующими API и SDK.

Чтобы включить нужные API и SDK, выполните следующие действия:

Консоль

1. Перейдите на страницу библиотеки Maps API в консоли Cloud Console, чтобы ознакомиться с API и SDK платформы Google Карт, которые можно включить для проекта:

   Перейти на страницу библиотеки Maps API

2. Нажмите на API или SDK, который вы хотите включить.
   • Если появится кнопка Включить, нажмите ее, чтобы активировать API или SDK.
   • Если отобразится кнопка Управление API, это означает, что API или SDK уже включен и вам ничего не нужно делать.
   • Нажав на любую из этих кнопок, вы перейдете на панель управления для выбранного API или SDK. Чтобы деактивировать API или SDK для проекта, нажмите на кнопку Отключить.

Cloud SDK

Следующая команда включает все 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 и следующих командах:

• gcloud services enable
• gcloud services disable

Чтобы включить Environment API, используйте следующую команду:

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

Примечание. Если вы включите Places API, вместе с ним будут активированы библиотека Places, Maps JavaScript API, Places SDK для Android и Places SDK для iOS.

Шаг 3

На этом шаге рассматривается только создание ключа API. Если у вас есть собственный ключ API, мы настоятельно рекомендуем настроить для него ограничения. Подробная информация приводится в разделе Использование ключей API.

Ключ API – это уникальный идентификатор, который используется для аутентификации запросов, связанных с вашим проектом. Он нужен для учета использования API и оплаты. С вашим проектом должен быть связан хотя бы один ключ API.

Чтобы создать ключ API, выполните следующие действия.

Cloud Console

1. Откройте страницу Google Maps Platform > Credentials (Платформа Google Карт > Учетные данные).

   Перейти к настройкам учетных данных

2. На странице Credentials (Учетные данные) нажмите Create credentials > API key (Создать учетные данные > Ключ API).
   Появится диалоговое окно с созданным ключом API.
3. Нажмите Close (Закрыть).
   Новый ключ API можно будет найти на странице Credentials (Учетные данные) в разделе API keys (Ключи API).
   Не забудьте настроить ограничения для ключа API, прежде чем использовать его в рабочей среде.

Cloud SDK

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

Прочитайте статьи о Google Cloud SDK, установке Cloud SDK и следующих командах:

• gcloud services api-keys create

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

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

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

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

1. Создайте новый проект Android Studio, используя шаблон Empty Views Activity (Пустое представление). В конфигурации проекта задайте для параметра Минимальная версия 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.0"
   # 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
   

   Примечание. Обязательно замените YOUR_API_KEY_HERE ключом API, который вы настроили для использования с Maps 3D SDK для Android.

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-карту в свое приложение.