Інтеграція Яндекс.Карт 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 та налаштуванням.