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 на версию 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

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

gcloud projects create "PROJECT"

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

gcloud alpha 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. Сохраните файл.

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

   MAPS_API_KEY=DEFAULT_API_KEY

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

8. Сохраните файл.
9. В файле 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 Maps на платформе Android, включая Maps SDK для Android. Для обратной совместимости API также поддерживает имя com.google.android.maps.v2.API_KEY . Это устаревшее имя позволяет выполнять аутентификацию только с помощью Android Maps API v2. Приложение может указать только одно из имен метаданных ключа API. Если указаны оба, API выдает исключение.

10. В 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"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    классный

    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"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

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

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

Дополнительные сведения об управлении зависимостями 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.