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 и сохранить свой ключ API:

1. В Android Studio откройте файл 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 уровня приложения и добавьте следующий код в элемент plugins .

   Круто

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

   Котлин

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

3. Если вы используете Android Studio, синхронизируйте свой проект с Gradle .
4. Откройте файл local.properties в каталоге вашего проекта и добавьте следующий код. Замените YOUR_API_KEY на ваш ключ API.

   MAPS_API_KEY=YOUR_API_KEY

5. В файле AndroidManifest.xml перейдите к com.google.android.geo.API_KEY и обновите атрибут android:value следующим образом:

   <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 выдаёт исключение.

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

Изучите код, предоставленный шаблоном. В частности, обратите внимание на следующие файлы в вашем проекте 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(libs.play.services.maps)
}

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

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.