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

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

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

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

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

Настройка Android-устройства

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

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

Создайте проект Google Maps в Android Studio

1. Откройте Android Studio и нажмите « Создать новый проект» в окне « Добро пожаловать в Android Studio» .

2. В окне « Новый проект» в категории « Телефон и планшет » выберите « Активность на Google Картах » и нажмите « Далее ».

3. Заполните форму активности Google Maps :

   • Установите язык на Java или Kotlin. Оба языка полностью поддерживаются Maps SDK для Android. Чтобы узнать больше о Kotlin, см. раздел Разработка приложений для Android с помощью Kotlin .

   • Установите для параметра « Минимум SDK » версию SDK, совместимую с вашим тестовым устройством. Вы должны выбрать версию, превышающую минимальную версию, требуемую Maps SDK для Android версии 18.0.x, которая в настоящее время соответствует Android API уровня 19 (Android 4.4, KitKat) или выше. См. примечания к выпуску для получения последней информации о требованиях к версии SDK.

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

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

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

6. Файл AndroidManifest.xml содержит инструкции по получению ключа Google Maps API и добавлению его в файл local.properties. Не добавляйте ключ API в файл AndroidManifest.xml . При этом ваш ключ API будет менее надежно защищен. Вместо этого следуйте инструкциям в следующих разделах, чтобы создать облачный проект и настроить ключ 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 для 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}" />
       

Примечание. Как показано выше, com.google.android.geo.API_KEY — рекомендуемое имя метаданных для ключа API. Ключ с таким именем можно использовать для аутентификации в нескольких API на основе Google Maps на платформе Android, включая Maps SDK для Android. Для обратной совместимости API также поддерживает имя com.google.android.maps.v2.API_KEY . Это устаревшее имя позволяет выполнять аутентификацию только в Android Maps API версии 2. Приложение может указать только одно из имен метаданных ключа API. Если указаны оба, API выдает исключение.

Посмотрите на код

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

Файл активности Карт

Файл действий с картами является основным действием для приложения и содержит код для управления картой и ее отображения. По умолчанию файл, определяющий действие, называется MapsActivity.java или, если вы установили Kotlin в качестве языка для своего приложения, MapsActivity.kt .

Основные элементы картографической деятельности:

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

• Объект GoogleMap обеспечивает доступ к данным карты и представлению. Это основной класс Maps SDK для Android. В руководстве по объектам карты более подробно описаны объекты SupportMapFragment и GoogleMap .

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

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

Файл активности карт содержит следующий код:

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 , которая определена в файле активности карт.
• android:name устанавливает имя класса фрагмента в SupportMapFragment , который является типом фрагмента, используемым в файле активности карт.

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

Следующие шаги

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

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

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