Создайте приложение 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.
Откройте Android Studio и нажмите «Новый проект» в окне «Добро пожаловать в Android Studio» .
В окне «Новый проект» в категории «Телефон и планшет» выберите «Нет активности» и нажмите «Далее» .
Заполните форму нового проекта :
Установите язык 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. Фрагменты для обоих языков конфигураций сборки показаны в следующих процедурах.
Нажмите «Готово» .
Android Studio запускает Gradle и собирает проект. Это может занять некоторое время.
Добавьте активность просмотров на Картах Google :
- Щелкните правой кнопкой мыши папку
app
в вашем проекте. Выберите «Создать» > «Google» > «Активность просмотров на Картах Google» .
В диалоговом окне «Новая активность Android» установите флажок «Активность запуска» .
Выберите Готово .
Дополнительные сведения см. в разделе Добавление кода из шаблона.
- Щелкните правой кнопкой мыши папку
По завершении сборки Android Studio открывает файлы
AndroidManifest.xml
иMapsActivity
. Ваше действие может иметь другое имя, но оно будет тем, которое вы настроили во время установки.
Настройте свой проект Google Cloud
Выполните необходимые шаги по настройке Cloud Console, перейдя на следующие вкладки:
Шаг 1
Консоль
В Google Cloud Console на странице выбора проекта нажмите « Создать проект» , чтобы начать создание нового облачного проекта.
Убедитесь, что для вашего облачного проекта включена оплата. Убедитесь, что для вашего проекта включена оплата .
Google Cloud предлагает пробную версию за 0,00 доллара США. Срок действия пробной версии истекает либо по истечении 90 дней, либо после того, как на счету будет накоплено средств на сумму 300 долларов США, в зависимости от того, что наступит раньше. Отменить в любое время. Платформа Google Maps предлагает регулярный ежемесячный кредит в размере 200 долларов США. Дополнительные сведения см. в разделах Кредиты на счете выставления счетов и Выставление счетов .
Облачный SDK
gcloud projects create "PROJECT"
Узнайте больше о Google Cloud SDK , установке Cloud SDK и следующих командах:
Шаг 2
Чтобы использовать платформу Google Maps, вам необходимо включить API или SDK, которые вы планируете использовать в своем проекте.
Консоль
Облачный SDK
gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
Узнайте больше о Google Cloud SDK , установке Cloud SDK и следующих командах:
Шаг 3
Этот шаг проходит только через процесс создания ключа API. Если вы используете свой ключ API в рабочей среде, мы настоятельно рекомендуем вам ограничить использование ключа API. Дополнительную информацию можно найти на странице «Использование ключей API» для конкретного продукта.
Ключ API — это уникальный идентификатор, который удостоверяет подлинность запросов, связанных с вашим проектом, для целей использования и выставления счетов. У вас должен быть хотя бы один ключ API, связанный с вашим проектом.
Чтобы создать ключ API:
Консоль
Перейдите на платформу Google Maps > страницу «Учетные данные» .
- На странице «Учетные данные» нажмите «Создать учетные данные» > «Ключ API» .
В диалоговом окне создания ключа API отображается только что созданный ключ API. - Нажмите «Закрыть».
Новый ключ API указан на странице «Учетные данные» в разделе «Ключи API» .
(Не забудьте ограничить ключ API перед его использованием в рабочей среде.)
Облачный SDK
gcloud alpha services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
Узнайте больше о Google Cloud SDK , установке Cloud SDK и следующих командах:
Добавьте ключ API в свое приложение
В этом разделе описывается, как хранить ключ API, чтобы ваше приложение могло безопасно ссылаться на него. Вам не следует проверять свой ключ API в системе контроля версий, поэтому мы рекомендуем хранить его в файле secrets.properties
, который находится в корневом каталоге вашего проекта. Дополнительные сведения о файле secrets.properties
см. в разделе Файлы свойств Gradle .
Чтобы упростить эту задачу, мы рекомендуем вам использовать плагин Secrets Gradle для Android .
Чтобы установить плагин Secrets Gradle для Android в свой проект Google Maps:
- В Android Studio откройте файл
build.gradle
илиbuild.gradle.kts
верхнего уровня и добавьте следующий код в элемент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") } }
- Откройте файл
build.gradle
уровня модуля и добавьте следующий код в элементplugins
.классный
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
Котлин
plugins { id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
- В файле
build.gradle
на уровне модуля убедитесь, что дляtargetSdk
иcompileSdk
установлено значение 34. - Сохраните файл и синхронизируйте проект с Gradle .
- Откройте файл
secrets.properties
в каталоге верхнего уровня, а затем добавьте следующий код. ЗаменитеYOUR_API_KEY
своим ключом API. Сохраните свой ключ в этом файле, посколькуsecrets.properties
не подлежит проверке в системе контроля версий.MAPS_API_KEY=YOUR_API_KEY
- Сохраните файл.
Создайте файл
local.defaults.properties
в каталоге верхнего уровня, в той же папке, что и файлsecrets.properties
, а затем добавьте следующий код.MAPS_API_KEY=DEFAULT_API_KEY
Целью этого файла является предоставление резервного местоположения для ключа API, если файл
secrets.properties
не найден, чтобы сборка не завершалась сбоем. Это может произойти, если вы клонируете приложение из системы контроля версий, в которой отсутствуетsecrets.properties
, и вы еще не создали файлsecrets.properties
локально, чтобы предоставить свой ключ API.- Сохраните файл.
- В файле
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}" />
Note:
com.google.android.geo.API_KEY
is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the namecom.google.android.maps.v2.API_KEY
. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception. -
In Android Studio, open your module-level
build.gradle
orbuild.gradle.kts
file and edit thesecrets
property. If thesecrets
property does not exist, add it.Edit the properties of the plugin to set
propertiesFileName
tosecrets.properties
, setdefaultPropertiesFileName
tolocal.defaults.properties
, and set any other properties.Groovy
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
содержит следующую зависимость карт, которая требуется для 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" />
Развертывание и запуск приложения
Когда вы успешно запустите приложение, оно отобразит карту с центром в Сиднее, Австралия, с маркером города, как показано на следующем снимке экрана.
Чтобы развернуть и запустить приложение:
- В Android Studio щелкните пункт меню «Выполнить» (или значок кнопки воспроизведения), чтобы запустить приложение.
- При появлении запроса на выбор устройства выберите один из следующих вариантов:
- Выберите устройство Android, подключенное к вашему компьютеру.
- Либо выберите переключатель «Запустить эмулятор» и выберите виртуальное устройство, которое вы настроили.
- Нажмите ОК . Android Studio запустит Gradle для создания вашего приложения, а затем отобразит результаты на вашем устройстве или в эмуляторе. Прежде чем приложение запустится, может пройти несколько минут.
Следующие шаги
Настройка карты . В этом документе описывается, как настроить начальные параметры и настройки времени выполнения вашей карты, такие как положение камеры, тип карты, компоненты пользовательского интерфейса и жесты.
Добавьте карту в свое приложение Android (Kotlin) . В этой кодовой лаборатории вы познакомитесь с приложением, демонстрирующим некоторые дополнительные функции Maps SDK для Android.
Используйте библиотеку Maps Android KTX . Эта библиотека расширений Kotlin (KTX) позволяет вам воспользоваться преимуществами нескольких функций языка Kotlin при использовании Maps SDK для Android.