Краткое руководство 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, щелкнув следующие вкладки:

Шаг 1

Консоль

  1. В Google Cloud Console на странице выбора проекта нажмите «Создать проект» , чтобы начать создание нового облачного проекта.

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

  2. Убедитесь, что биллинг включен для вашего облачного проекта. Убедитесь, что для вашего проекта включено выставление счетов .

    Google Cloud предлагает пробную версию с оплатой в размере 0,00 долларов США. Срок действия пробной версии истекает либо через 90 дней, либо после того, как на счете накопится 300 долларов США, в зависимости от того, что наступит раньше. Отменить в любое время. Платформа Google Maps имеет регулярный ежемесячный кредит в размере 200 долларов США. Дополнительные сведения см. в разделах Кредиты платежного аккаунта и Выставление счетов .

Облачный SDK

gcloud projects create "PROJECT"

Узнайте больше о Google Cloud SDK , установке Cloud SDK и следующих командах:

Шаг 2

Чтобы использовать платформу Google Maps, необходимо включить API или SDK, которые вы планируете использовать в своем проекте.

Консоль

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

Облачный SDK

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

Узнайте больше о Google Cloud SDK , установке Cloud SDK и следующих командах:

Шаг 3

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

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

Чтобы создать ключ API:

Консоль

  1. Перейдите на страницу « Платформа Google Карт» > «Учетные данные ».

    Перейти на страницу учетных данных

  2. На странице Учетные данные щелкните Создать учетные данные > Ключ API .
    В диалоговом окне создания ключа API отображается только что созданный ключ API.
  3. Щелкните Закрыть.
    Новый ключ API указан на странице Учетные данные в разделе Ключи API .
    (Не забудьте ограничить ключ API перед его использованием в рабочей среде.)

Облачный SDK

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

Узнайте больше о Google Cloud SDK , установке Cloud SDK и следующих командах:

Добавьте ключ 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" />

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

Скриншот с картой и маркером по центру Syndney Australia.

Когда вы успешно запустите приложение, оно отобразит карту с центром в Сиднее, Австралия, с маркером на городе, как показано на следующем снимке экрана.

Чтобы развернуть и запустить приложение:

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

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

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

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

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