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

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

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

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

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

Примечание. Если в вашей среде разработки используется другая версия Android Studio или Gradle, возможно, вам придется изменить шаги в зависимости от вашей среды. Дополнительные сведения о версиях Android Studio и Gradle см. в разделе Плагин Android Gradle и совместимость с Android Studio .

Настройка устройства Android

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

• Чтобы использовать устройство Android, следуйте инструкциям в разделе «Запуск приложений на аппаратном устройстве» .
• Чтобы использовать эмулятор Android, вы можете создать виртуальное устройство и установить эмулятор с помощью диспетчера виртуальных устройств Android (AVD) , который входит в состав Android Studio.
  Примечание. Если вы решите использовать эмулятор Android, убедитесь, что вы выбрали устройство со значком Play , , отображается в столбце Play Store . Этот значок означает, что эти профили полностью совместимы с CTS и могут использовать образы системы, включающие приложение Play Store:

  

Создайте проект 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 см. в примечаниях к выпуску .

     Примечание. Если вы не уверены, какую версию SDK выбрать, нажмите ссылку «Помочь мне выбрать», чтобы отобразить информацию о распространении поддерживаемых Android SDK. Например, если вы выберете уровень Android API 21 («Lollipop»; Android 5.0) , ваше приложение должно работать на более чем 99 % устройств Android.

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

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

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

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

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

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

      

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

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

      Дополнительные сведения см. в разделе Добавление кода из шаблона.

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

   Внимание! Файл AndroidManifest.xml содержит инструкции по получению ключа API Google Maps и его последующем добавлению в файл local.properties . Не добавляйте ключ API в файл local.properties . При этом ваш ключ API будет храниться менее надежно. Вместо этого следуйте инструкциям в разделе «Настройка проекта Google Cloud» , чтобы создать проект Cloud и настроить ключ API.

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

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

Шаг 1

Консоль

1. В Google Cloud Console на странице выбора проекта нажмите «Создать проект» , чтобы начать создание нового облачного проекта.

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

2. Убедитесь, что для вашего облачного проекта включена оплата. Убедитесь, что для вашего проекта включена оплата .

   Google Cloud предлагает пробную версию стоимостью 0,00 доллара США. Срок действия пробной версии истекает либо по истечении 90 дней, либо после того, как на счету будет накоплено средств на сумму 300 долларов США, в зависимости от того, что наступит раньше. Отменить в любое время. Платформа Google Maps предлагает регулярный ежемесячный кредит в размере 200 долларов США. Дополнительные сведения см. в разделах Кредиты на счете выставления счетов и Выставление счетов .

Облачный SDK

gcloud projects create "PROJECT"

Узнайте больше о Google Cloud SDK , установке Cloud SDK и следующих командах:

• gcloud projects create

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

Шаг 2

Чтобы использовать платформу Google Maps, вам необходимо включить API или SDK, которые вы планируете использовать в своем проекте.

Консоль

Включите Maps SDK для Android

Облачный SDK

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

Узнайте больше о Google Cloud SDK , установке Cloud SDK и следующих командах:

• gcloud services enable
• gcloud services disable

Шаг 3

Этот шаг проходит только через процесс создания ключа API. Если вы используете свой ключ API в рабочей среде, мы настоятельно рекомендуем вам ограничить использование ключа API. Дополнительную информацию можно найти на странице «Использование ключей API» для конкретного продукта.

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

Чтобы создать ключ API:

Консоль

1. Перейдите на платформу Google Maps > страницу «Учетные данные» .

   Перейдите на страницу учетных данных

2. На странице «Учетные данные» нажмите «Создать учетные данные» > «Ключ API» .
   В диалоговом окне создания ключа API отображается только что созданный ключ API.
3. Нажмите Закрыть.
   Новый ключ API указан на странице «Учетные данные» в разделе «Ключи API» .
   (Не забудьте ограничить ключ API перед его использованием в рабочей среде.)

Облачный SDK

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

Узнайте больше о Google Cloud SDK , установке Cloud SDK и следующих командах:

• gcloud alpha services api-keys create

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

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

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

Примечание. Последние системные требования и инструкции по установке см. в документации по плагину Secrets Gradle для Android на GitHub.

Чтобы установить плагин 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 не подлежит проверке в системе контроля версий.
   Примечание. Если файл secrets.properties не существует, создайте его в той же папке, что и файл local.properties .

   MAPS_API_KEY=YOUR_API_KEY

6. Сохраните файл.

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

   Примечание. Введите код, как показано. Не заменяйте DEFAULT_API_KEY своим ключом API.

   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 SDK для Android.

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