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

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

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

Как настроить среду разработки

1. Вам потребуется Android Studio версии Arctic Fox или более поздней. Если у вас нет этого инструмента, скачайте и установите его.
2. Убедитесь, что вы используете в Android Studio плагин Android Gradle версии 7.0 или более поздней.

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

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

1. Откройте Android Studio и нажмите Create new project (Создать проект) в окне Welcome to Android Studio (Добро пожаловать в Android Studio).

2. В окне New Project (Новый проект) найдите категорию Phone and Tablet (Телефоны и планшеты). Выберите Google Maps Activity (Операция с Google Картами) и нажмите Next (Далее).

3. Заполните форму 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 можно найти в примечаниях к выпуску.

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

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

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

6. Файл AndroidManifest.xml содержит инструкции о том, как получить ключ Google Maps API и добавить его в файл local.properties. Не добавляйте ключ API в файл AndroidManifest.xml, поскольку это небезопасно. Вместо этого выполните инструкции по созданию проекта Google Cloud и настройке ключа API, приведенные в разделах ниже.

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

Выполните настройку Cloud Console на указанных ниже вкладках.

gcloud projects create "PROJECT"

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

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

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

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

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

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

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

2. Откройте файл build.gradle уровня модуля и добавьте в элемент plugins указанный ниже код.

   id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
       

3. Сохраните файл и синхронизируйте проект с Gradle.
4. Откройте файл local.properties в каталоге уровня проекта и добавьте в этот файл приведенный ниже код. Укажите вместо YOUR_API_KEY свой ключ API.

   MAPS_API_KEY=YOUR_API_KEY
       

5. Сохраните файл.
6. В файле 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 для карты содержит следующий код:

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));
    }
}

      

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" />

Выполните развертывание и запустите приложение

Если приложение запущено успешно, в нем будет показана карта, отцентрированная по координатам Сиднея (Австралия). Вы увидите маркер, как на скриншоте.

Следуйте инструкциям ниже.

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.