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.

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

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

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

3. Заполните форму « Новый проект» :

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

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

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

4. Нажмите «Готово» .

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

5. Добавьте активность «Виды» в Google Maps :

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

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

      

   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 Maps на платформе 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 предоставляет доступ к данным карты и ее отображению. Это основной класс SDK карт для Android. В руководстве по объектам карт объекты SupportMapFragment и GoogleMap описаны более подробно.

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

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

Файл Gradle модуля

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

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

Чтобы узнать больше об управлении зависимостью 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) : В этом практическом руководстве вы увидите, как создать приложение, демонстрирующее некоторые дополнительные возможности SDK для карт для Android.

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