Начало работы с MapKit для Android

В этом руководстве объясняется как установить и настроить библиотеку MapKit и создать карту с меткой для определенной локации.

Шаг 1. Получите API-ключ для работы с MapKit

Перед тем, как использовать MapKit SDK в своем приложении, вам нужно получить API-ключ.

  1. Перейдите в Кабинет Разработчика.

  2. Авторизуйтесь с учетной записью Яндекса или зарегистрируйте новый аккаунт.

  3. Нажмите Подключить API и выберите MapKit – мобильный SDK.

  4. Введите информацию о себе и своем проекте, выберите тарифный план и нажмите Продолжить.

  5. После того, как ваш API-ключ будет успешно создан, он будет доступен на вкладке Интерфейсы API → MapKit – мобильный SDK.

Примечание

Активация API-ключей занимает около 15 минут.

Шаг 2. Добавьте библиотеку MapKit в проект

Библиотека MapKit SDK для Android 5.0 и более поздних версий доступна в репозитории Maven Central.

  1. Создайте новый проект или откройте существующий, например, в Android Studio.

  2. Откройте файл build.gradle проекта. В секции repositories добавьте репозитории Maven Central и Google Maven:

    repositories {
    ...
    mavenCentral()
    maven {
         url "http://maven.google.com/"
    }
}

  3. Откройте файл build.gradle приложения (модуля). В секции dependencies добавьте зависимость:

    dependencies
{
    // Облегченная библиотека, содержит только карту, слой пробок,
    // LocationManager, UserLocationLayer
    // и возможность скачивать офлайн-карты (только в платной версии).
    implementation 'com.yandex.android:maps.mobile:4.6.1-lite'

    // Полная библиотека в дополнение к lite версии предоставляет автомобильную маршрутизацию,
    // веломаршрутизацию, пешеходную маршрутизацию и маршрутизацию на общественном транспорте,
    // поиск, suggest, геокодирование и отображение панорам.
    // implementation 'com.yandex.android:maps.mobile:4.6.1-full'
}

  4. Синхронизируйте проект, чтобы применить изменения. Например, в Android Studio можно нажать Sync Now или выбрать в меню File → Synchronize. Дождитесь окончания синхронизации.

    Если синхронизация завершилась успешно, при компиляции библиотека будет добавлена в проект автоматически.

Шаг 3. Добавьте API-ключ для MapKit

Для MapKit SDK необходимо, чтобы вы установили API-ключ с помощью MapKitFactory.setApiKey.

Рекомендуем сделать это в методе Application.onCreate:

override fun onCreate() {
    super.onCreate()
    MapKitFactory.setApiKey("YOUR_API_KEY")
}

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

  1. Откройте или создайте файл local.properties проекта. Добавьте следующее свойство, подставив вместо YOUR_API_KEY значение вашего API-ключа:

    MAPKIT_API_KEY=YOUR_API_KEY

    Примечание

    Убедитесь, что файл local.properties игнорируется системой контроля версий.

  2. Откройте файл build.gradle проекта. Добавьте код для загрузки API-ключа из файла local.properties:

    ext {
    mapkitApiKey = getMapkitApiKey()
}

private String getMapkitApiKey() {
    def properties = new Properties()
    project.file("local.properties").withInputStream { properties.load(it) }
    return properties.getProperty("MAPKIT_API_KEY", "")
}

  3. В файле build.gradle приложения в поле BuildConfig введите значение переменной mapkitApiKey (в нее загружается API-ключ):

    defaultConfig {
    // ...

    buildConfigField "String", "MAPKIT_API_KEY", "\"${mapkitApiKey}\""
}

  4. Добавьте API-ключ в MapKitFactory, используя поле BuildConfig.MAPKIT_API_KEY:

    override fun onCreate() {
    super.onCreate()
    MapKitFactory.setApiKey(BuildConfig.MAPKIT_API_KEY)
}

Шаг 4. Добавьте карту

  1. Добавьте MapView в xml-разметку Activity:

    <com.yandex.mapkit.mapview.MapView
    android:id="@+id/mapview"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

  2. Чтобы инициализировать библиотеку MapKit, вызовите метод MapKitFactory.initialize в Activity.onCreate. Создайте приватное свойство mapView: MapView.

    private lateinit var mapView: MapView

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    MapKitFactory.initialize(this)
    setContentView(R.layout.activity_main)
    mapView = findViewById(R.id.mapview)
}

    Важно

    С помощью вызова MapKitFactory.initialize(Context) загружаются все необходимые для MapKit нативные библиотеки.

  3. Отправьте события onStart и onStop в MapKitFactory и MapView, переопределив методы Activity.onStart и Activity.onStop для Activity:

    override fun onStart() {
    super.onStart()
    MapKitFactory.getInstance().onStart()
    mapView.onStart()
}

override fun onStop() {
    mapView.onStop()
    MapKitFactory.getInstance().onStop()
    super.onStop()
}

    Иначе MapKit не сможет отображать карту и прекратит ее обработку, когда Activity с картой станет невидимой для пользователей.

Создайте и запустите приложение. Пример приложения с кликабельной картой:

Карта с наименьшим увеличением

Чтобы изменить положение или масштаб карты, используйте метод Map.move:

override fun onCreate(savedInstanceState: Bundle?) {
    // ...
    map.move(
        CameraPosition(
            Point(55.751225, 37.629540),
            /* zoom = */ 17.0f,
            /* azimuth = */ 150.0f,
            /* tilt = */ 30.0f
        )
    )
}

Map.move принимает на вход аргумент CameraPosition, который полностью задает положение, масштаб, наклон и азимут карты.

Карты по умолчанию поддерживают несколько действий: перемещение, поворот, изменение масштаба и наклон.

Без дополнительной настройки карта будет отображаться с минимально возможным масштабом для экрана пользователя.

Пример Activity после изменения карты:

Карта после применения

Шаг 5. Обратите внимание при дальнейшей работе

MapKit хранит слабые ссылки на передаваемые ему Listener-объекты. Необходимо самим хранить ссылку на них в памяти:

val cameraListener = CameraListener { _, _, _, _ ->
    // ...
}
mapView.mapWindow.map.addCameraListener(cameraListener)

Примечание

По умолчанию методы всех Listener-объектов и платформенных интерфейсов вызываются на главном потоке, если в документации метода не сказано обратное.

Шаг 6. Отображение метки на карте

Изменим приложение таким образом, чтобы вы могли показывать на карте кликабельную метку.

  1. Добавьте в проект ресурс png для изображения метки.

    Например, есть изображение, и оно доступно по идентификатору R.drawable.ic_pin.

    Значок метки

  2. Добавьте метку для коллекции Map.getMapObjects в определенное место.

    Используйте ImageProvider.fromResource, чтобы создать экземпляр ImageProvider для изображения метки.

    override fun onCreate(savedInstanceState: Bundle?) {
    // ...
    val imageProvider = ImageProvider.fromResource(this, R.drawable.ic_pin)
    val placemark = mapView.map.mapObjects.addPlacemark().apply {
        geometry = Point(59.935493, 30.327392)
        setIcon(imageProvider)
    }
}

  3. Чтобы подписаться на нажатия на созданную метку, используйте метод MapObject.addTapListener.

    private val placemarkTapListener = MapObjectTapListener { _, point ->
    Toast.makeText(
        this@MainActivity,
        "Tapped the point (${point.longitude}, ${point.latitude})",
        Toast.LENGTH_SHORT
    ).show()
    true
}

override fun onCreate(savedInstanceState: Bundle?) {
    // ...
    placemark.addTapListener(placemarkTapListener)
}

Соберите и запустите приложение. На карте есть метка с вашим изображением. Коснитесь метки, и появится всплывающее сообщение:

Карта после нажатия метки

Исходный код

Полные примеры кода из руководства вы можете найти в приложении map-with-placemark в нашем репозитории на GitHub.

Предыдущая
О MapKit
Следующая
Объекты карты
В этой статье: