Maps SDK для Android: краткое руководство

Создайте приложение для Android, отображающее карту, используя шаблон Google Maps Views для Android Studio. Если у вас есть существующий проект Android Studio, который вы хотите настроить, см. раздел Настройка проекта Android Studio .

Это краткое руководство предназначено для разработчиков, знакомых с основами разработки Android-приложений на Kotlin или Java.

О среде разработки

Это краткое руководство было разработано с использованием Android Studio Hedgehog и плагина Android Gradle версии 8.2.

Настройте Android-устройство

Чтобы запустить приложение, использующее Maps SDK для Android, необходимо развернуть его на устройстве Android или эмуляторе Android на базе Android 5.0 или выше, включающем API Google.

• Чтобы использовать устройство Android, следуйте инструкциям в разделе Запуск приложений на аппаратном устройстве .
• Чтобы использовать эмулятор Android, вы можете создать виртуальное устройство и установить эмулятор с помощью диспетчера виртуальных устройств Android (AVD), который входит в состав Android Studio.

Создайте проект Google Maps в Android Studio

Процедура создания проекта Google Maps в Android Studio была изменена во Flamingo и более поздних версиях Android Studio.

1. Откройте Android Studio и нажмите «Новый проект» в окне «Добро пожаловать в Android Studio» .

2. В окне «Новый проект» в категории «Телефоны и планшеты» выберите «Нет активности» , а затем нажмите «Далее» .

3. Заполните форму нового проекта :

   • Выберите язык Java или Kotlin. Оба языка полностью поддерживаются Maps SDK для Android. Подробнее о Kotlin см. в статье «Разработка приложений для Android на Kotlin» .

   • Установите для параметра «Минимальная версия SDK» значение, совместимое с вашим тестовым устройством. Необходимо выбрать версию выше минимальной версии, требуемой Maps SDK для Android версии 19.0.x, которая соответствует уровню Android API 21 («Lollipop»; Android 5.0) или выше. Актуальную информацию о требованиях к версии SDK см. в примечаниях к выпуску .

   • Выберите язык конфигурации сборки : Kotlin DSL или Groovy DSL. Фрагменты кода для обоих языков конфигурации сборки показаны в следующих процедурах.

4. Нажмите кнопку Готово .

   Android Studio запускает Gradle и выполняет сборку проекта. Это может занять некоторое время.

5. Добавьте активность просмотров Google Карт :

   1. Щелкните правой кнопкой мыши папку app в вашем проекте.

   2. Выберите Создать > Google > Активность просмотров Карт Google .

      

   3. В диалоговом окне «Новая активность Android» установите флажок «Активность запуска» .

   4. Выберите Готово .

      Для получения дополнительной информации см. раздел Добавление кода из шаблона.

6. После завершения сборки Android Studio открывает файлы AndroidManifest.xml и MapsActivity . Имя вашей активности может быть другим, но оно совпадает с тем, которое вы указали при настройке.

Настройте свой проект Google Cloud

Выполните необходимые шаги по настройке облачной консоли, перейдя по следующим вкладкам:

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

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

Добавьте ключ API в свое приложение

В этом разделе описывается, как сохранить ключ API, чтобы приложение могло безопасно ссылаться на него. Не следует регистрировать ключ API в системе контроля версий, поэтому мы рекомендуем хранить его в файле secrets.properties , расположенном в корневом каталоге вашего проекта. Подробнее о файле secrets.properties см. в разделе Файлы свойств Gradle .

Чтобы упростить эту задачу, мы рекомендуем вам использовать плагин Secrets Gradle для Android .

Чтобы установить плагин Secrets Gradle для Android в вашем проекте Google Maps:

1. В Android Studio откройте файл build.gradle.kts или build.gradle верхнего уровня и добавьте следующий код в элемент dependencies под buildscript .

   Котлин

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   Круто

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

2. Откройте файл build.gradle.kts или build.gradle на уровне модуля и добавьте следующий код в элемент plugins .

   Котлин

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Круто

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. В файле build.gradle.kts или build.gradle на уровне модуля убедитесь, что для targetSdk и compileSdk задано значение 34.
4. Синхронизируйте свой проект с Gradle .
5. Откройте файл secrets.properties в каталоге верхнего уровня и добавьте следующий код. Замените YOUR_API_KEY вашим ключом API. Сохраните свой ключ в этом файле, поскольку secrets.properties не подлежит проверке в системе контроля версий.

   MAPS_API_KEY=YOUR_API_KEY

6. Создайте файл local.defaults.properties в каталоге верхнего уровня, в той же папке, что и файл secrets.properties , а затем добавьте следующий код.

   MAPS_API_KEY=DEFAULT_API_KEY

   Этот файл предназначен для резервного хранения ключа API на случай, если файл secrets.properties не будет найден, чтобы предотвратить сбои сборок. Это может произойти, если вы клонируете приложение из системы контроля версий, в которой отсутствует файл secrets.properties , и вы ещё не создали файл secrets.properties локально для хранения ключа API.

7. В файле AndroidManifest.xml перейдите к com.google.android.geo.API_KEY и обновите android:value attribute . Если тег <meta-data> отсутствует, создайте его как дочерний элемент тега <application> .

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

   Примечание: com.google.android.geo.API_KEY — рекомендуемое имя метаданных для ключа API. Ключ с таким именем можно использовать для аутентификации в нескольких API на базе Google Карт на платформе Android, включая Maps SDK для Android. Для обратной совместимости API также поддерживает имя com.google.android.maps.v2.API_KEY . Это устаревшее имя позволяет выполнять аутентификацию только в Android Maps API v2. Приложение может указать только одно из имён метаданных ключа API. Если указаны оба, API выдаёт исключение.

8. В Android Studio откройте файл build.gradle.kts или build.gradle на уровне модуля и отредактируйте свойство secrets . Если свойство secrets отсутствует, добавьте его.

   Отредактируйте свойства плагина, чтобы задать для propertiesFileName значение secrets.properties , для defaultPropertiesFileName — значение local.defaults.properties , а также задать любые другие свойства.

   Котлин

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
           

   Круто

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
           

Посмотрите на код

Изучите код, предоставленный шаблоном. В частности, обратите внимание на следующие файлы в вашем проекте Android Studio.

Файл активности Карт

Файл активности карт — это основная активность приложения, содержащая код для управления и отображения карты. По умолчанию файл, определяющий активность, называется MapsActivity.java или, если вы выбрали Kotlin в качестве языка приложения, MapsActivity.kt .

Основные элементы картографической деятельности:

• Объект SupportMapFragment управляет жизненным циклом карты и является родительским элементом пользовательского интерфейса приложения.

• Объект GoogleMap предоставляет доступ к данным карты и её представлению. Это основной класс Maps SDK для Android. Более подробно объекты SupportMapFragment и GoogleMap описаны в руководстве по объектам карт .

• Функция moveCamera центрирует карту в точке с координатами LatLng для Сиднея, Австралия. Первыми настройками при добавлении карты обычно являются местоположение карты и параметры камеры, такие как угол обзора, ориентация карты и уровень масштабирования. Подробнее см. в руководстве «Камера и вид» .

• Функция addMarker добавляет маркер к координатам Сиднея. Подробности см. в руководстве по маркерам .

Файл модуля Gradle

Файл модуля build.gradle.kts включает следующую зависимость карт, которая требуется для Maps SDK для Android.

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

Дополнительную информацию об управлении зависимостью от Карт см. в разделе Управление версиями .

XML-файл макета

Файл activity_maps.xml — это XML-файл макета , определяющий структуру пользовательского интерфейса приложения. Он расположен в каталоге res/layout . В файле activity_maps.xml объявлен фрагмент, включающий следующие элементы:

• tools:context устанавливает активность фрагмента по умолчанию на MapsActivity , которая определена в файле активности карты.
• android:name задает имя класса фрагмента как SupportMapFragment , что является типом фрагмента, используемым в файле активности карт.

Файл макета XML содержит следующий код:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

Разверните и запустите приложение

При успешном запуске приложения на экране отобразится карта с центром в Сиднее (Австралия) и маркером на городе, как показано на следующем снимке экрана.

Чтобы развернуть и запустить приложение:

1. В Android Studio нажмите пункт меню «Запустить» (или значок кнопки воспроизведения), чтобы запустить приложение.
2. При появлении запроса на выбор устройства выберите один из следующих вариантов:
   • Выберите Android-устройство, подключенное к вашему компьютеру.
   • Либо выберите переключатель «Запустить эмулятор» и выберите настраиваемое вами виртуальное устройство.
3. Нажмите «ОК» . Android Studio запустит Gradle для сборки вашего приложения и отобразит результаты на вашем устройстве или эмуляторе. Запуск приложения может занять несколько минут.

Следующие шаги

• Настройка карты : в этом документе описывается, как настроить начальные и динамические параметры вашей карты, такие как положение камеры, тип карты, компоненты пользовательского интерфейса и жесты.

• Добавьте карту в свое приложение Android (Kotlin) : в этой лабораторной работе вы познакомитесь с приложением, демонстрирующим некоторые дополнительные функции Maps SDK для Android.

• Используйте библиотеку Maps Android KTX : эта библиотека расширений Kotlin (KTX) позволяет использовать преимущества нескольких функций языка Kotlin при использовании Maps SDK для Android.