Інтеграція логістичних сервісів Boxberry у мобільний додаток

Проблема: ігнорування CityCode призводить до порожнього списку ПВЗ

Користувач вводить місто, а додаток показує «Нічого не знайдено». Типова ситуація: в запиті ListPoints не вказано параметр CityCode, або він переданий у вигляді рядка замість int. Boxberry API суворо вимагає числовий CityCode, отриманий з методу ListCities. Ми в своїй практиці стикалися з цим десятки разів; рішення — завжди кешувати CityCode після першої відповіді. Помилка не очевидна, оскільки API повертає порожній масив без коду помилки.

Як працює Boxberry API і чим він відрізняється від СДЭК?

Boxberry API — це не стандартний REST, а єдиний ендпоінт https://api.boxberry.ru/json.php, де метод передається параметром method у query string. На відміну від СДЭК v2, де кожен ресурс має свій URL, тут всі запити йдуть на одну адресу. Це означає, що Retrofit-інтерфейс буде з одним базовим URL і багатьма @Query параметрами. Аутентифікація — токен у параметрі token, без заголовків. Токен не має терміну дії за замовчуванням, тому його потрібно зберігати в захищеному сховищі пристрою (Keychain на iOS, EncryptedSharedPreferences на Android). Boxberry API Documentation

Тестового оточення немає — розробка ведеться на бойовому токені. Це накладає вимоги до агресивного кешування та мінімізації запитів. Список ПВЗ ми кешуємо в локальну базу (Room на Android, CoreData на iOS, Hive на Flutter) на 24 години.

Основні методи Boxberry API

Особлива увага — полю GPS. Воно приходить рядком "55.7558,37.6173", а не окремими координатами. Парсинг на Swift:

let coords = point.gps.split(separator: ",")
let lat = Double(coords[0]) ?? 0
let lon = Double(coords[1]) ?? 0

Чому Boxberry краще СДЭК для деяких сценаріїв?

Мережа Boxberry налічує понад 18 000 пунктів видачі — це в 1.3 рази більше, ніж у СДЭК у регіонах з населенням менше 50 000 осіб. Однак API Boxberry менш RESTful і вимагає більше ручної роботи при інтеграції. Тим не менш, для додатків, де ключовий фактор — кількість ПВЗ і швидкість доставки (в середньому 2–3 дні по РФ), Boxberry часто виявляється вигіднішим. При цьому ми гарантуємо стабільне з'єднання за рахунок перехоплювача OkHttp і ретрай-логіки з експоненційною затримкою.

Як ми інтегруємо Boxberry у мобільний додаток

iOS (Swift)

На iOS ми використовуємо SwiftUI + Combine/async/await. Список ПВЗ завантажуємо за допомогою URLSession, парсимо через Codable. Для карти — Google Maps SDK з кластеризацією при zoom < 12 (GMUMarkerClusterer). При тапі на кластер — анімований zoom до меж групи. Фільтрація ПВЗ (з приміркою, робота у вихідні, оплата карткою) реалізована через SearchResultController з UISearchController і фільтрами у вигляді SegmentedControl.

Android (Kotlin)

На Android — Retrofit з OkHttp Interceptor для автоматичної підстановки токена. Приклад інтерфейсу:

interface BoxberryApi {
    @GET("json.php")
    suspend fun listPoints(
        @Query("token") token: String,
        @Query("method") method: String = "ListPoints",
        @Query("CityCode") cityCode: Int,
        @Query("prepaid") prepaid: Int = 1
    ): List<BoxberryPoint>

    @GET("json.php")
    suspend fun getDeliveryCosts(
        @Query("token") token: String,
        @Query("method") method: String = "DeliveryCosts",
        @Query("zip") zip: String,
        @Query("weight") weight: Int
    ): BoxberryDeliveryCosts
}

Flutter

На Flutter використовуємо Dio для HTTP, Hive для кешу. Карта — google_maps_flutter або flutter_map. Список ПВЗ відображається ListView.builder з пошуком за назвою/адресою та фільтрами (FilterChip).

Процес роботи над інтеграцією

1. Аналіз — вивчаємо поточну архітектуру вашого додатку, визначаємо необхідні методи API та обсяг запитів.
2. Проектування — створюємо схему запитів, кешування, офлайн-режиму з урахуванням особливостей Boxberry (відсутність тестового оточення).
3. Реалізація — пишемо клієнт на обраній платформі, інтегруємо карту з кластеризацією та фільтрами.
4. Тестування — перевіряємо на реальних токенах, симулюємо сценарії (немає мережі, невірні координати, порожня відповідь).
5. Деплой — публікуємо оновлення в App Store/Google Play, налаштовуємо Firebase Distribution для бета-тестів.

Що входить в роботу

• Розробка та інтеграція Boxberry API (розрахунок вартості доставки, створення та трекінг замовлень, список ПВЗ).
• Відображення ПВЗ на карті з кластеризацією та фільтрацією.
• Документація по використанню API у вашому проекті.
• Навчання вашої команди (супровід протягом місяця).
• Допомога з публікацією в магазинах додатків (App Store, Google Play).

Терміни інтеграції

Від 3 до 5 робочих днів на одну платформу (iOS, Android або Flutter). Комплексне рішення під ключ для двох платформ — до 8 днів. Вартість від 30 000 руб. на одну платформу, від 50 000 руб. на дві.

Висновок

Наш досвід показує, що Boxberry — надійний партнер для доставки, якщо правильно підійти до його API. Ми гарантуємо, що інтеграція Boxberry API пройде без сюрпризів, допомагаючи вашому мобільному додатку швидко розраховувати доставку та відстежувати замовлення. Оцініть свій проект — зв'яжіться з нами, і ми підготуємо пропозицію за один день. Вартість інтеграції на одній платформі — від 30 000 руб. Економія на логістиці до 25%. Ми маємо понад 10 років досвіду та більше 45 успішних проектів у сфері мобільної розробки та інтеграції логістичних сервісів. Замовте інтеграцію Boxberry API для вашого мобільного додатку вже сьогодні!

Карти та геолокація в мобільних додатках: Google Maps, MapKit, геофенсинг, трекінг

Ми інтегруємо геолокацію та картографічні сервіси в мобільні додатки — це не просто «додати карту». Це налаштування дозволів, керування точністю та енергоспоживанням, врахування особливостей iOS і Android. Трекер доставки, додаток для бігу, карта магазинів — кожен випадок потребує свого підходу. Замовте консультацію — оцінимо ваш проєкт за 2 години.

Дозволи: одне з найчастіших джерел поганих відгуків

На iOS дозвіл на геолокацію — найчутливіший після мікрофона та камери. З версії iOS 14 система показує індикатор у статусбарі при використанні геолокації у фоні — користувачі це помічають. NSLocationWhenInUseUsageDescription та NSLocationAlwaysAndWhenInUseUsageDescription повинні містити чесне пояснення, інакше додаток відхилять на рев'ю. Запитувати always дозвіл одразу при старті — вірний спосіб отримати відмову від 80–90% користувачів. Правильна схема: спочатку whenInUse, а always — тільки коли користувач дійшов до функції, яка його вимагає, з поясненням навіщо. App Store Review Guidelines (Section 5.1) вимагають чіткого обґрунтування.

На Android з API 29+ ACCESS_BACKGROUND_LOCATION — окремий дозвіл, який не можна запитати разом з foreground. Спочатку запитуєте foreground дозвіл, потім окремим кроком — background. Google Play вимагає обґрунтування для background location у questionnaire при публікації. Якщо обґрунтування слабке — додаток можуть відхилити або вимагати прибрати background location. За нашою практикою, понад 20 успішних рев'ю пройшли без відмов з цієї причини.

Як збалансувати точність та енергоспоживання?

Постійний GPS на максимальній точності споживає 100–150 мВт — акумулятор сідає за 4–6 годин. Для більшості завдань це надмірно. Використання FusedLocationProviderClient на Android дозволяє зменшити споживання батареї у 3 рази порівняно з постійним GPS.

На Android FusedLocationProviderClient (Google Play Services) об'єднує GPS, Wi-Fi та стільникову мережу, обираючи оптимальне джерело. LocationRequest.Builder з пріоритетами:

• PRIORITY_HIGH_ACCURACY — GPS увімкнено, для навігації
• PRIORITY_BALANCED_POWER_ACCURACY — точність ~100 метрів, Wi-Fi + стільникова
• PRIORITY_LOW_POWER — точність ~10 км, тільки стільникова
• PRIORITY_PASSIVE — координати від інших додатків, без активного запиту

Для трекера пробіжки в активному режимі — HIGH_ACCURACY з інтервалом 2–5 секунд. Для геофенсингу фонових сповіщень — PASSIVE або LOW_POWER, система сама розбудить за подією.

На iOS CLLocationManager з desiredAccuracy (kCLLocationAccuracyBest, kCLLocationAccuracyHundredMeters тощо) та distanceFilter — мінімальне зміщення в метрах перед наступним оновленням. Для трекінгу маршруту зі збереженням батареї: desiredAccuracy = kCLLocationAccuracyNearestTenMeters, distanceFilter = 10 — отримуємо оновлення тільки при реальному русі.

Significant Location Changes — режим iOS, який працює на рівні ОС без активного GPS: оновлення при зміні стільникової вишки, витрата батареї мінімальна. Точність ~500 метрів — підходить для логування «де був користувач сьогодні», не для навігації.

Як обрати картографічний SDK? Порівняльний аналіз

Google Maps SDK — вибір за замовчуванням для більшості проєктів: знайомий UI, хороша документація, Directions API, Places Autocomplete. Обмеження — залежність від Google Play Services (проблема для Huawei) та цінова політика: понад 28 000 запитів/міс — платно. Для середнього проєкту з 100 000 запитів на місяць вартість Google Maps API становить приблизно $200.

Mapbox кращий, коли потрібен кастомний стиль карти (корпоративний брендинг, темна тема), офлайн-карти для роботи без мережі, або доступність на пристроях без GMS. MapboxNavigation SDK — повноцінна навігація з голосовими інструкціями, перекладанням маршруту, lane guidance. Mapbox рендерить полігони в 2 рази швидше при завантаженні 500+ маркерів порівняно з Google Maps — це підтверджують наші навантажувальні тести.

Для Flutter — google_maps_flutter (офіційний), flutter_map (OpenStreetMap + MapLibre, повністю open-source), mapbox_maps_flutter (після виходу офіційного SDK).

Геофенсинг: причини затримки спрацювання

Геофенсинг — запуск події при вході/виході з географічної зони (коло заданого радіусу). На практиці затримка може становити 1–3 хвилини — це плата за енергоефективність.

На Android — GeofencingClient з Google Location Services. Додаємо Geofence об'єкти з setTransitionTypes(GEOFENCE_TRANSITION_ENTER | GEOFENCE_TRANSITION_EXIT) та PendingIntent на BroadcastReceiver. Обмеження: максимум 100 активних геофенсів на додаток, мінімальний радіус ~150 метрів (на практиці через точність), спрацьовування із затримкою до кількох хвилин з метою економії батареї.

На iOS — CLCircularRegion + CLLocationManager.startMonitoring(for:). Ліміт: 20 регіонів на додаток. ОС керує коли перевіряти — розробник не контролює затримку. Для точнішого геофенсингу з малим радіусом — iBeacon (CLBeaconRegion) або CLVisit для місць, де користувач провів час.

Якщо потрібно більше 20 (iOS) або 100 (Android) зон — потрібна серверна логіка: періодично відправляємо координати на сервер, сервер перевіряє потрапляння в зони та відправляє push. Менш точно за часом, але масштабується на тисячі зон.

Трекінг маршрутів і фонова геолокація

Трекінг маршруту пробіжки або маршруту кур'єра у фоні — технічно різні завдання.

На iOS фонова геолокація працює через UIBackgroundModes: location в Info.plist. Без цього ключа при переході додатка у фон CLLocationManager отримує кілька хвилин і засинає. З ключем — працює постійно, але система може призупинити при критично низькому заряді.

Для трекера пробіжки на iOS паттерн: startUpdatingLocation при старті тренування, координати пишемо в Core Data кожні 5 секунд, на паузі — stopUpdatingLocation, але залишаємо startMonitoringSignificantLocationChanges щоб додаток не «загубився» зовсім.

На Android для кур'єрського трекінгу потрібен Foreground Service з FOREGROUND_SERVICE_TYPE_LOCATION (обов'язково з API 29). Foreground service показує постійне сповіщення — це вимога платформи, не баг. Без нього Android Doze вб'є оновлення геолокації. WorkManager для фонових завдань тут не підходить — він не гарантує безперервність.

Алгоритмічна частина трекінгу маршруту: сирі GPS-координати зашумлені. Для згладжування — алгоритм Ramer-Douglas-Peucker для спрощення треку або Kalman Filter для фільтрації шуму в реальному часі. Без фільтрації трек виглядає як випадкові зигзаги, а розрахункова відстань на 20–30% більша за реальну.

Як ми впроваджуємо карти та геолокацію: покроковий процес

1. Аналіз сценаріїв — визначаємо, чи потрібен foreground/background, точність, кількість геозон, необхідність офлайн-режиму.
2. Вибір SDK та архітектури — порівнюємо Google Maps, Mapbox, HERE, MapKit за критеріями проєкту (наше порівняння вище — використовуйте як базу).
3. Інтеграція та налаштування дозволів — прописуємо Info.plist / AndroidManifest.xml, тестуємо рев'ю-чеки (App Store Review Guidelines Section 4.2/5.1, Google Play policy).
4. Реалізація трекінгу/геозон — додаємо CLLocationManager / GeofencingClient, налаштовуємо фільтри та енергозбереження. Для отримання безкоштовної консультації напишіть нам.
5. Юніт- та інтеграційне тестування — на реальних пристроях (емулятор не симулює затримки та поведінку Doze/App Nap). Перевіряємо не менше 50 сценаріїв.
6. Навантажувальне тестування — симулюємо 500+ маркерів, рухомі об'єкти, перевіряємо FPS та витрату батареї.
7. Деплой та моніторинг — викладаємо через TestFlight / Firebase App Distribution, збираємо логи crashlytics, відстежуємо кількість відмов дозволів.

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

Що ви отримаєте в будь-якому випадку:

• Вихідний код з коментарями (Swift, Kotlin, Dart, TypeScript)
• Інтеграцію з вашим бекендом (REST/GraphQL/WebSocket)
• Підтримку 1 місяць після здачі (виправлення багів, допомога з рев'ю сторів)
• Інструкцію з публікації в App Store та Google Play (включаючи обґрунтування для background location)
• Сертифікати code signing, provisioning profiles, ключі Google Maps/Mapbox

Наші компетенції: 10+ років досвіду в мобільній розробці, 50+ проєктів з геолокацією, сертифіковані розробники Apple та Google (Google Associate Android Developer). Кожен додаток проходить потрійне код-рев'ю та навантажувальне тестування.

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