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

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

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

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

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

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

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

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

В Android Studio создайте проект Google Карт

Процедура создания проекта Google Maps в Android Studio была изменена в Flamingo и более поздних версиях 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. Нажмите Finish (Готово).

    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 Console и нажмите 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, который находится в корневом каталоге проекта. Подробные сведения о файле secrets.properties можно найти в описании файлов свойств Gradle.

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

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

  1. В Android Studio откройте файл build.gradle на корневом уровне и добавьте в элемент dependencies, принадлежащий элементу buildscript, указанный ниже код.

    Groovy

    buildscript {
    dependencies {
        // ...
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}

    Kotlin

    buildscript {
    dependencies {
        // ...
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}
  2. Откройте файл build.gradle на уровне приложения и добавьте в элемент plugins указанный ниже код.

    Groovy

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

    Kotlin

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. Если вы используете Android Studio, синхронизируйте проект с Gradle.
  4. Откройте файл local.properties в каталоге уровня проекта и добавьте в этот файл приведенный ниже код. Укажите вместо YOUR_API_KEY свой ключ API. 
    MAPS_API_KEY=YOUR_API_KEY
  5. В файле 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 вызывает исключение.

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

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

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

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

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

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

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

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

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

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

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

dependencies {

    // Maps SDK for Android
    implementation(libs.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.