Вы можете создать приложение Android с картой, используя шаблон Google Карт для Android Studio. Если у вас уже есть проект Android Studio и вы хотите изменить его настройки, перейдите к описанию конфигурации.
Это краткое руководство предназначено для тех, кто имеет опыт разработки приложений для Android на языках Java или Kotlin.
Как настроить среду разработки
- Вам потребуется Android Studio версии Arctic Fox или более поздней. Если у вас нет этого инструмента, скачайте и установите его.
- Убедитесь, что вы используете в Android Studio плагин Android Gradle версии 7.0 или более поздней.
Как настроить устройство Android
Чтобы запустить приложение с Maps SDK для Android, разверните его на устройстве Android или в эмуляторе ОС Android 4.0 или более поздней версии, поддерживающем API Google.
- Инструкции по запуску приложений на устройствах Android доступны здесь.
- Чтобы воспользоваться эмулятором Android, создайте виртуальное устройство и установите на него эмулятор с помощью Менеджера AVD, который доступен в Android Studio.
Как создать проект Google Карт в Android Studio
Откройте Android Studio и нажмите Create new project (Создать проект) в окне Welcome to Android Studio (Добро пожаловать в Android Studio).
В окне New Project (Новый проект) найдите категорию Phone and Tablet (Телефоны и планшеты). Выберите Google Maps Activity (Операция с Google Картами) и нажмите Next (Далее).
Заполните форму Google Maps Activity (Операция с Google Картами):
В поле Language (Язык) выберите Java или Kotlin. Maps SDK для Android полностью поддерживает оба этих языка. Узнайте больше о Kotlin.
Укажите минимальную версию SDK (она должна быть совместима с вашим тестовым устройством). Кроме того, эта версия должна быть более поздней, чем минимальная версия, требуемая для работы с Maps SDK для Android 18.0.x. Сейчас это API уровня 19 (Android 4.4, KitKat) и выше. Самую новую информацию о требованиях к версии SDK можно найти в примечаниях к выпуску.
Нажмите Finish (Готово).
Android Studio запустит Gradle и выполнит сборку проекта. Это может занять некоторое время.
Когда сборка будет завершена, в Android Studio откроются файлы
AndroidManifest.xml
иMapsActivity
. Ваш объект activity может иметь другое название, если вы указали его при настройке.Файл
AndroidManifest.xml
содержит инструкции о том, как получить ключ Google Maps API и добавить его в файл local.properties. Не добавляйте ключ API в файлAndroidManifest.xml
, поскольку это небезопасно. Вместо этого выполните инструкции по созданию проекта Google Cloud и настройке ключа API, приведенные в разделах ниже.
Настройка проекта Google Cloud
Выполните настройку Cloud Console на указанных ниже вкладках.
Шаг 1
Cloud Console
-
Чтобы приступить к созданию проекта, перейдите на страницу выбора проекта в консоли Google Cloud Console и нажмите Создать проект.
-
Убедитесь, что для проекта Google Cloud включены платежные функции.
Мы предлагаем бесплатный пробный период для использования Google Cloud. Он длится 90 дней или пока сумма расходов не достигнет 300 долл. США, в зависимости от того, что произойдет раньше. Отменить его можно в любое время. Для работы с платформой Google Карт предоставляется ежемесячный кредит на сумму 200 долл. США. Ознакомьтесь с информацией о кредитах в платежных аккаунтах и платежных функциях.
Cloud SDK
gcloud projects create "PROJECT"
Прочитайте статьи о Google Cloud SDK, установке Cloud SDK и следующих командах:
Шаг 2
Для работы с платформой Google Карт вам потребуется включить API и SDK, которые будут использоваться в проекте.
Консоль
Cloud SDK
gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
Прочитайте статьи о Google Cloud SDK, установке Cloud SDK и следующих командах:
Шаг 3
Этот шаг относится к процессу создания ключа API. Если у вас есть собственный ключ API, мы настоятельно рекомендуем настроить для него ограничения. Дополнительную информацию о том, как использовать ключи API для разных продуктов, вы найдете на этой странице.
Ключ API – это уникальный идентификатор, который используется для аутентификации запросов, связанных с вашим проектом. Он нужен для учета использования API и оплаты. С вашим проектом должен быть связан хотя бы один ключ API.
Чтобы создать его, выполните следующие действия:
Cloud Console
-
Откройте страницу Google Maps Platform > Credentials (Платформа Google Карт > Учетные данные).
-
На странице Учетные данные нажмите Создать учетные данные > Ключ API.
Появится диалоговое окно с созданным ключом API. -
Нажмите Close (Закрыть).
Новый ключ API можно будет найти в разделе Ключи API на странице Учетные данные.
Не забудьте настроить ограничения для ключа API, прежде чем использовать его в рабочей среде.
Cloud SDK
gcloud alpha services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
Прочитайте статьи о Google Cloud SDK, установке Cloud SDK и следующих командах:
Как добавить в приложение ключ API
В этом разделе рассказывается, как настроить защищенный вызов ключа API вашим приложением. Вводить ключ API в систему управления версиями нежелательно, поэтому мы рекомендуем хранить его в файле local.properties
в корневом каталоге проекта. Подробные сведения о файле local.properties
можно найти в описании файлов свойств Gradle.
Чтобы быстрее выполнить эту задачу, используйте плагин Secrets Gradle Plugin for Android. Чтобы установить плагин и настроить хранение ключа API, выполните следующие действия:
- В Android Studio откройте файл
build.gradle
уровня проекта и добавьте в элементdependencies
, принадлежащий элементуbuildscript
, указанный ниже код.plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false }
- Откройте файл
build.gradle
уровня модуля и добавьте в элементplugins
указанный ниже код.id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
- Сохраните файл и синхронизируйте проект с Gradle.
- Откройте файл
local.properties
в каталоге уровня проекта и добавьте в этот файл приведенный ниже код. Укажите вместоYOUR_API_KEY
свой ключ API.MAPS_API_KEY=YOUR_API_KEY
- Сохраните файл.
- В файле
AndroidManifest.xml
найдите разделcom.google.android.geo.API_KEY
и изменитеandroid:value attribute
следующим образом:<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
Примечание. Как показано выше, рекомендуемое имя метаданных для ключа API – com.google.android.geo.API_KEY
. Ключ с таким именем может использоваться для аутентификации нескольких API созданных на основе Google Карт для платформы Android, включая Maps SDK for Android. Для обеспечения обратной совместимости API также поддерживает имя com.google.android.maps.v2.API_KEY
. Это устаревшее имя обеспечивает аутентификацию только для Android Maps API версии 2. Приложение позволяет указать только одно из имен в метаданных ключа API. Если указаны оба имени, API вызывает исключение.
Проанализируйте код
Изучите код, содержащийся в шаблоне. В частности, просмотрите указанные ниже файлы в проекте Android Studio.
Файл activity для карты
Файл activity для карты – это основной операционный файл для приложения. Он содержит код для отображения карты и управления ей. По умолчанию такой файл называется MapsActivity.java
. Если же в качестве языка для приложения вы выбрали Kotlin, он будет называться MapsActivity.kt
.
Основные элементы файла activity
Объект
SupportMapFragment
управляет жизненным циклом карты и является родительским элементом для интерфейса приложения.Объект
GoogleMap
предоставляет доступ к данным карты и ее представлению. Это основной класс в Maps SDK для Android. Дополнительную информацию об объектахSupportMapFragment
иGoogleMap
вы можете найти в этом руководстве.Функция
moveCamera
центрирует карту по координатамLatLng
(Сидней, Австралия). Как правило, при добавлении карты первым делом нужно изменить настройки местоположения и камеры: угол обзора, ориентацию карты, масштаб и т. п. Подробнее…Функция
addMarker
добавляет маркер к координатам Сиднея. Подробнее…
Файл activity для карты содержит следующий код:
Java
import android.os.Bundle; import androidx.appcompat.app.AppCompatActivity; import com.google.android.gms.maps.CameraUpdateFactory; import com.google.android.gms.maps.GoogleMap; import com.google.android.gms.maps.OnMapReadyCallback; import com.google.android.gms.maps.SupportMapFragment; import com.google.android.gms.maps.model.LatLng; import com.google.android.gms.maps.model.MarkerOptions; public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback { private GoogleMap mMap; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_maps); // Obtain the SupportMapFragment and get notified when the map is ready to be used. SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager() .findFragmentById(R.id.map); mapFragment.getMapAsync(this); } /** * Manipulates the map once available. * This callback is triggered when the map is ready to be used. * This is where we can add markers or lines, add listeners or move the camera. In this case, * we just add a marker near Sydney, Australia. * * If Google Play services is not installed on the device, the user will be prompted to install * it inside the SupportMapFragment. This method will only be triggered once the user has * installed Google Play services and returned to the app. */ @Override public void onMapReady(GoogleMap googleMap) { mMap = googleMap; // Add a marker in Sydney and move the camera LatLng sydney = new LatLng(-34, 151); mMap.addMarker(new MarkerOptions() .position(sydney) .title("Marker in Sydney")); mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney)); } }
Kotlin
import androidx.appcompat.app.AppCompatActivity import android.os.Bundle import com.google.android.gms.maps.CameraUpdateFactory import com.google.android.gms.maps.GoogleMap import com.google.android.gms.maps.OnMapReadyCallback import com.google.android.gms.maps.SupportMapFragment import com.google.android.gms.maps.model.LatLng import com.google.android.gms.maps.model.MarkerOptions internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback { private lateinit var mMap: GoogleMap override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_maps) // Obtain the SupportMapFragment and get notified when the map is ready to be used. val mapFragment = supportFragmentManager .findFragmentById(R.id.map) as SupportMapFragment mapFragment.getMapAsync(this) } /** * Manipulates the map once available. * This callback is triggered when the map is ready to be used. * This is where we can add markers or lines, add listeners or move the camera. In this case, * we just add a marker near Sydney, Australia. * If Google Play services is not installed on the device, the user will be prompted to install * it inside the SupportMapFragment. This method will only be triggered once the user has * installed Google Play services and returned to the app. */ override fun onMapReady(googleMap: GoogleMap) { mMap = googleMap // Add a marker in Sydney and move the camera val sydney = LatLng(-34.0, 151.0) mMap.addMarker(MarkerOptions() .position(sydney) .title("Marker in Sydney")) mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney)) } }
Gradle-файл модуля
Файл модуля build.gradle
содержит указанные ниже зависимости, которые требуются для работы Maps SDK для Android.
dependencies { implementation 'com.google.android.gms:play-services-maps:18.1.0' // ... }
Подробнее об управлении зависимостями для карт…
XML-файл макета
Файл activity_maps.xml
– это XML-файл макета, который определяет структуру интерфейса в приложении. Он находится в каталоге res/layout
.
Файл activity_maps.xml
объявляет фрагмент со следующими элементами:
- Элемент
tools:context
задаетMapsActivity
в качестве действия по умолчанию для фрагмента. Это действие определено в файле activity. - Элемент
android:name
задаетSupportMapFragment
в качестве имени класса для фрагмента. Этот тип фрагмента используется в файле activity.
XML-файл макета содержит следующий код:
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:id="@+id/map"
tools:context=".MapsActivity"
android:name="com.google.android.gms.maps.SupportMapFragment" />
Выполните развертывание и запустите приложение
Если приложение запущено успешно, в нем будет показана карта, отцентрированная по координатам Сиднея (Австралия). Вы увидите маркер, как на скриншоте.
Следуйте инструкциям ниже.
- Чтобы запустить приложение, в Android Studio выберите пункт меню Run (Запустить) или нажмите кнопку со значком воспроизведения.
- Когда откроется окно с предложением выбрать устройство, выполните одно из следующих действий:
- Выберите устройство Android, подключенное к вашему компьютеру.
- Вы также можете установить переключатель Launch emulator (Запустить эмулятор) и выбрать виртуальное устройство, которое настроили ранее.
- Нажмите ОК. Android Studio запустит Gradle для сборки приложения, а затем отобразит результаты на устройстве или в эмуляторе. Для запуска приложения может потребоваться несколько минут.
Дальнейшие действия
Настройте карту. В этой статье рассказывается о том, как задать для карты исходные настройки и настройки времени выполнения, например положение камеры, тип карты, компоненты интерфейса и жесты.
Добавьте карту в свое приложение Android (Kotlin). В этом руководстве рассказывается, как использовать в приложении дополнительные функции Maps SDK для Android.
Используйте библиотеку Maps Android KTX. Это набор расширений Kotlin (KTX) содержит несколько языковых функций Kotlin, полезных при использовании Maps SDK для Android.