Інтеграція Яндекс.Карт SDK у мобільний додаток

Ми часто бачимо, як розробники витрачають дні на інтеграцію Яндекс.Карт SDK, стикаючись з неочевидними помилками: то IllegalStateException через пропущену ініціалізацію, то витік пам'яті через забутий onStop(). Наша команда мобільної розробки з 5-річним досвідом інтегрувала Яндекс.Карти у більш ніж 30 проектах — від каршерінгу до геосоціальних мереж. В одному з проектів для доставки їжі ми скоротили розмір APK на 60%, перейшовши з Full на Lite, і зменшили час завантаження карти з 3 до 1.5 секунд за рахунок лінивої ініціалізації.

Які завдання вирішуємо з Яндекс.Картами

Яндекс.Карти — безальтернативний вибір для додатків, що працюють на території України, Росії та СНД. Основні сценарії:

• Відображення карт з маркерами та кастомними іконками — точки інтересу, магазини, заклади.
• Побудова маршрутів — автомобільних, пішохідних, з урахуванням пробок.
• Пошук та геокодування — адреси, організації, категорії (кафе, аптеки).
• Офлайн-карти — для роботи без інтернету (версія Full).

Кожен сценарій вимагає правильного налаштування SDK, інакше виникають баги: неточне позиціонування, помилки пошуку, краші при масштабуванні. Ми вирішуємо ці проблеми на етапі проектування.

Як вибрати версію SDK: Full чи Lite?

Яндекс надає дві версії, і вибір критичний для розміру додатку. Порівняємо їх характеристики:

MapKit Lite у 2.5 рази менший за Full і підходить для 80% проектів — якщо не потрібні офлайн та транзитні маршрути. Ми допомагаємо з вибором та налаштуванням обох версій.

Чому важлива правильна ініціалізація?

API-ключ отримується в developer.tech.yandex.ru. Згідно з документацією, ключ не прив'язується до Bundle ID / applicationId при створенні — обмеження налаштовуються окремо в кабінеті. Типова помилка: пропущений MapKitFactory.initialize() до створення MapView. Це видає IllegalStateException з повідомленням, що ключ не встановлено, хоча setApiKey викликаний.

Android:

// build.gradle
implementation("com.yandex.android:maps.mobile:4.6.1-full")

// Application.onCreate()
MapKitFactory.setApiKey("YOUR_API_KEY")
MapKitFactory.initialize(this)

iOS (Swift Package Manager):

// Package.swift dependency:
// .package(url: "https://github.com/yandex/mapkit-ios-demo", from: "4.6.1")
// AppDelegate / App init:
import YandexMapsMobile
MapKit.setApiKey("YOUR_API_KEY")

Пропуск lifecycle-методів — ще одна поширена причина збоїв. На Android обов'язково викликайте mapView.onStart() та mapView.onStop() у відповідних lifecycle-обробниках. Інакше SDK продовжує рендеринг у фоні, що призводить до витоків пам'яті. В одному з проектів ми скоротили споживання пам'яті на 30%, просто додавши ці виклики.

Як уникнути типових помилок при інтеграції?

Ось чек-лист, який ми використовуємо в кожному проекті:

• [ ] MapKitFactory.initialize() викликаний до першого створення MapView.
• [ ] mapView.onStart() та mapView.onStop() додані в активність/фрагмент.
• [ ] API-ключ не містить зайвих пробілів і скопійований правильно.
• [ ] Версія SDK обрана відповідно до вимог (Full або Lite).
• [ ] Для офлайн-функцій використовується тільки Full-версія.

Ці прості кроки усувають 90% проблем, з якими звертаються до нас розробники.

Розбір кейсу: пошук та відображення маршрутів

Розглянемо інтеграцію пошуку організацій та побудови маршруту в додатку доставки. На Android це потребує роботи з SearchManager та DrivingRouter.

Пошук:

val searchManager = SearchFactory.getInstance()
        .createSearchManager(SearchManagerType.COMBINED)
val searchSession = searchManager.submit(
    "кафе поруч",
    VisibleRegionUtils.toPolygon(mapView.mapWindow.map.visibleRegion),
    SearchOptions().apply {
        searchTypes = SearchType.BIZ.value
        resultPageSize = 20
    },
    object : Session.SearchListener {
        override fun onSearchResponse(response: Response) {
            for (item in response.collection.children) {
                val point = item.obj?.geometry?.firstOrNull()?.point ?: continue
                addMarker(point, item.obj?.name ?: "")
            }
        }

        override fun onSearchError(error: Error) {}
    }
)

Маршрути:

val drivingRouter = DirectionsFactory.getInstance().createDrivingRouter(DrivingRouterType.COMBINED)
val points = listOf(
    RequestPoint(Point(55.7558, 37.6173), RequestPointType.WAYPOINT, null, null),
    RequestPoint(Point(59.9343, 30.3351), RequestPointType.WAYPOINT, null, null)
)
drivingRouter.requestRoutes(
    points,
    DrivingOptions().apply {
        routesCount = 1
    },
    VehicleOptions(),
    object : DrivingSession.DrivingRouteListener {
        override fun onDrivingRoutes(routes: MutableList<DrivingRoute>) {
            if (routes.isNotEmpty()) {
                mapView.mapWindow.map.mapObjects.addPolyline(routes[0].geometry)
            }
        }

        override fun onDrivingRoutesError(error: Error) {}
    }
)

Критично важливо не забути lifecycle-методи onStart/onStop. Пропуск onStop веде до витоку пам'яті та продовження рендерингу у фоні. У проекті для доставки ми фіксували зростання споживання пам'яті на 40% за годину роботи при відсутності onStop.

Процес роботи

Інтеграцію ділимо на етапи:

Терміни та що входить

Орієнтовні терміни: від 1 до 3 днів залежно від складності. Базова карта з маркерами — 1 день. Пошук + маршрути + кастомні іконки — 2-3 дні. Вартість розраховується індивідуально та включає:

• Вихідний код інтеграції з коментарями.
• Документацію з налаштування та підтримки.
• Доступ до репозиторію з прикладами.
• Гарантію роботи протягом 30 днів після здачі.

Типові помилки при інтеграції

• Пропущений MapKitFactory.initialize() на Android — IllegalStateException.
• Не викликано mapView.onStop() — витік пам'яті та продовження рендерингу у фоні.
• Використання Lite-версії для офлайн-функцій — краш при спробі завантажити офлайн-карту.
• Некоректне управління життєвим циклом MapView у Fragment — втрата карти при зміні конфігурації.

Ми гарантуємо, що інтеграція пройде без цих проблем. Зв'яжіться з нами, щоб обговорити ваш проект. Оцінимо завдання протягом робочого дня. Замовте консультацію — ми допоможемо з вибором версії SDK та налаштуванням.