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

Вы можете создать приложение 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.
Примечание. Если вы используете эмулятор Android, выберите устройство со значком воспроизведения () в столбце Google Play. Этот значок подтверждает, что профиль полностью совместим с CTS и может использовать образы системы, которые содержат приложение Google Play.

Как создать проект 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 можно найти в примечаниях к выпуску.
  
  Примечание. Если вы не знаете, какую версию SDK выбрать, ознакомьтесь с информацией о распространении поддерживаемых Android SDK. Например, если вы выберете API 19: Android 4.4 (KitKat), ваше приложение сможет работать на 99 % всех устройств Android.
Нажмите 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 и следующих командах:

gcloud projects create

Шаг 2

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

Консоль

Включить 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.

Чтобы создать его, выполните следующие действия:

Cloud Console

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

Перейти на страницу Credentials (Учетные данные)
На странице Учетные данные нажмите Создать учетные данные > Ключ 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 и следующих командах:

gcloud alpha services api-keys create

Как добавить в приложение ключ 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.