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

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

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

Среда разработки

Рекомендуем использовать последнюю стабильную версию Android Studio и плагина Android Gradle.

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

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

  • Чтобы использовать устройство Android, следуйте инструкциям о том, как запускать приложения на физических устройствах.
  • Чтобы воспользоваться эмулятором Android, создайте виртуальное устройство и установите эмулятор с помощью Диспетчера устройств, который доступен в Android Studio.

Как создать проект Google Карт в Android Studio

  1. Откройте Android Studio и нажмите New Project (Новый проект) в окне Welcome to Android Studio (Добро пожаловать в Android Studio).

  2. В окне New Project (Новый проект) найдите категорию Phone and Tablet (Телефоны и планшеты). Выберите No Activity (Без объекта activity) и нажмите Next (Далее).

  3. Заполните форму New Project (Новый проект).

    • В поле Language (Язык) выберите Java или Kotlin. Maps SDK для Android полностью поддерживает оба этих языка. Узнайте больше о разработке приложений для Android на языке Kotlin.

    • Задайте значение в поле Minimum SDK (Минимальная версия SDK). Она должна быть совместима с вашим тестовым устройством, а также быть выше минимальной версии, поддерживаемой Maps SDK для Android 20.0.x (уровень API 23 для Android 6.0 Marshmallow и выше). Самую новую информацию о требованиях к версии SDK можно найти в примечаниях к выпуску.

    • В поле Build configuration language (Язык конфигурации сборки) выберите Kotlin DSL или Groovy DSL. В описанных ниже процедурах показаны фрагменты кода на обоих языках конфигурации сборки.

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

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

  5. Как добавить объект activity для режимов просмотра Google Карт

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

    2. Выберите New > Google > Google Maps Views Activity (Создать > Google > Объект activity для режимов просмотра Google Карт).

      Добавление объекта activity для Карт.

    3. В диалоговом окне New Android Activity (Новый объект activity для Android) установите флажок Launcher Activity (Объект activity для средства запуска).

    4. Нажмите Finish (Готово).

      Подробнее о том, как добавить код из шаблона…

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

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

Ознакомьтесь с инструкциями на вкладках ниже.

Шаг 1

Консоль

  1. Перейдите на страницу выбора проекта в консоли Google Cloud и нажмите Create Project (Создать проект).

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

  2. Убедитесь, что для проекта Google Cloud включены платежные функции.

    Мы предлагаем бесплатный пробный период для использования Google Cloud. Он длится 90 дней или пока сумма расходов не достигнет 300 долл. США в зависимости от того, что произойдет раньше. Отказаться от предложения можно в любое время. Ознакомьтесь с информацией о бонусах в платежных аккаунтах и об оплате.

Cloud SDK

gcloud projects create "PROJECT"

Прочитайте статьи о Google Cloud SDK, установке Cloud SDK и следующих командах:

Шаг 2

Для работы с платформой Google Карт вам потребуется включить API и SDK, которые будут использоваться в проекте.

Cloud Console

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

Cloud SDK

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

Прочитайте статьи о Google Cloud SDK, установке Cloud SDK и следующих командах:

Шаг 3

На этом шаге рассматривается только создание ключа API. Если у вас есть собственный ключ API, мы настоятельно рекомендуем настроить для него ограничения. Подробная информация приводится в разделе Использование ключей API.

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

Чтобы создать ключ API, выполните следующие действия.

Cloud Console

  1. Откройте страницу Google Maps Platform > Credentials (Платформа Google Карт > Учетные данные).

    Перейти к настройкам учетных данных

  2. На странице Credentials (Учетные данные) нажмите Create credentials > API key (Создать учетные данные > Ключ API).
    Появится диалоговое окно с созданным ключом API.
  3. Нажмите Close (Закрыть).
    Новый ключ API можно будет найти на странице Credentials (Учетные данные) в разделе API keys (Ключи API).
    Не забудьте настроить ограничения для ключа API, прежде чем использовать его в рабочей среде.

Cloud SDK

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

Прочитайте статьи о Google Cloud SDK, установке Cloud SDK и следующих командах:

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

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

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

Чтобы установить плагин Secrets Gradle для Android и сохранить ключ API, выполните следующие действия:

  1. В Android Studio откройте файл build.gradle.kts или build.gradle верхнего уровня и добавьте в блок plugins приведенный ниже код.

    Kotlin

    plugins {
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
}

    Groovy

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
  2. Откройте файл build.gradle.kts или build.gradle уровня модуля и добавьте в элемент plugins приведенный ниже код.

    Kotlin

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}

    Groovy

    plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. Если вы используете Android Studio, синхронизируйте проект с Gradle.
  4. Откройте файл secrets.properties в каталоге верхнего уровня и добавьте приведенный ниже код. Замените YOUR_API_KEY своим ключом API. Добавьте secrets.properties в файл .gitignore (или исключите его из системы управления версиями другим способом), чтобы ключ API не попал в систему управления версиями. 
    MAPS_API_KEY=YOUR_API_KEY

  5. Создайте файл local.defaults.properties в каталоге верхнего уровня (там же, где хранится файл secrets.properties), а затем добавьте указанный ниже код.

    MAPS_API_KEY=DEFAULT_API_KEY

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

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

  7. В Android Studio откройте файл build.gradle.kts или build.gradle на уровне модуля и измените свойство secrets. Если свойства secrets нет, добавьте его.

    Измените свойства плагина, чтобы задать для propertiesFileName значение "secrets.properties", а для defaultPropertiesFileName – "local.defaults.properties". Также можно задать другие свойства.

    Kotlin

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
}

    Groovy

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
}

Как анализировать код

Изучите код, содержащийся в шаблоне. В частности, просмотрите указанные ниже файлы в проекте Android Studio.

Файл activity для карты

В файле activity для карты содержится основной объект activity приложения. Он содержит код для отображения карты и управления ей. По умолчанию такой файл называется MapsActivity.java. Если же в качестве языка для приложения вы выбрали Kotlin, он будет называться MapsActivity.kt.

Основные элементы файла activity

  • Объект SupportMapFragment управляет жизненным циклом карты и является родительским элементом для интерфейса приложения.

  • Объект GoogleMap предоставляет доступ к данным карты и ее представлению. Это основной класс в Maps SDK для Android. Дополнительную информацию об объектах SupportMapFragment и GoogleMap вы можете найти в этом руководстве.

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

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

Kotlin

// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney")
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

Java

// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
map.addMarker(new MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

Gradle-файл модуля

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

Kotlin

dependencies {

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

Groovy

dependencies {

    // Maps SDK for Android
    implementation "com.google.android.gms:play-services-maps:20.0.0"
}

Если в вашем проекте используется каталог версий Gradle (gradle/libs.versions.toml), определите зависимость play-services-maps в libs.versions.toml:

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

Подробнее об управлении зависимостями для карт…

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: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 выберите пункт меню Run (Запустить) или нажмите на значок воспроизведения, чтобы запустить свое приложение.
  2. Когда откроется окно с предложением выбрать устройство, выполните одно из следующих действий:
    • Выберите устройство Android, подключенное к вашему компьютеру.
    • Вы также можете установить переключатель Launch emulator (Запустить эмулятор) и выбрать виртуальное устройство, которое настроили ранее.
  3. Нажмите ОК. Android Studio запустит Gradle для сборки приложения, а затем выведет результаты на устройстве или в эмуляторе. Для запуска приложения может потребоваться несколько минут.

Дальнейшие действия

  • Настройте карту. В этом документе рассказывается о том, как задать для карты исходные настройки и настройки времени выполнения, например положение камеры, тип карты, компоненты интерфейса и жесты.

  • Добавьте карту в приложение для Android (Kotlin). В этой практической работе рассказывается, как использовать в приложении дополнительные функции Maps SDK для Android.

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