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

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

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

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

1. Вам обязательно потребуется Android Studio. Если у вас нет этого инструмента, скачайте и установите его.

2. Добавьте в Android Studio SDK сервисов Google Play. Maps SDK для Android является частью SDK сервисов Google Play, доступного в SDK Manager.

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

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

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

Создайте проект Google Карт

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. Это должна быть версия Android SDK, которую поддерживает ваше тестовое устройство.

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

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

Дополнительную информацию о создании проекта вы можете найти здесь.

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

Настройки в Cloud Console

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

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

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

Чтобы вам было проще работать, используйте Secrets Gradle Plugin для Android.

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

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

   id 'com.google.secrets_gradle_plugin' version '0.5'
       

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

   MAPS_API_KEY=YOUR_API_KEY
       

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

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example;

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;

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

      

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example.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
import com.google.maps.example.R

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:17.0.1'
    // ...
}

Подробнее об управлении зависимостями для карт…

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.