FlightObject і BCBP: як додати посадкові талони в Google Wallet

FlightObject і FlightClass для посадкових талонів

При спробі додати посадковий талон в Google Wallet розробники часто стикаються з проблемою: штрихкод не зчитується сканерами в аеропорту, а автооновлення статусу рейсу не приходять. Причина — нестандартний BCBP або неправильний IATA-код у FlightClass. У 80% випадків помилка в carrierIataCode позбавляє користувача сповіщень про затримки. У нас 5 років досвіду та 20+ проєктів з інтеграції Google Wallet для авіакомпаній. Стандарт IATA BCBP визначає структуру даних для сканування. Неправильне кодування призводить до відмов на гейтах. Економія від автоматизації посадки через Wallet є значною для великих авіакомпаній.

Проблеми інтеграції Google Wallet

Головна складність — правильна структура FlightClass та FlightObject. Помилка в flightHeader (наприклад, неправильний IATA-код авіакомпанії) вимикає автосповіщення. Друга проблема — генерація JWT з коректним BCBP. Багато розробників використовують довільний ідентифікатор, але сканери очікують стандарт IATA. Третя — верифікація issuer: без неї клас залишається в статусі UNDER_REVIEW, і автооновлення не працюють. Ми вирішуємо всі три задачі, гарантуючи коректну роботу в продакшені.

Типові помилки та їх вирішення

Структура FlightClass та FlightObject

FlightClass описує рейс — авіакомпанію, номер, маршрут. FlightObject — конкретного пасажира та місце. Ключова відмінність: FlightObject підтримує автоматичні оновлення статусу рейсу від Google, якщо issuer верифіковано. Нижче приклади створення на Python.

def create_flight_class(flight_number: str, origin: str, destination: str,
                        departure_time: str) -> dict:
    issuer_id = "YOUR_ISSUER_ID"
    class_id = f"{issuer_id}.flight_{flight_number}"

    return {
        "id": class_id,
        "issuerName": "AirCompany",
        "flightHeader": {
            "carrier": {
                "carrierIataCode": "SU",
                "airlineLogo": {
                    "sourceUri": {"uri": "https://yourapp.com/logo.png"}
                },
                "airlineName": {
                    "defaultValue": {"language": "ru", "value": "Аэрофлот"}
                }
            },
            "flightNumber": flight_number,
            "operatingCarrier": {
                "carrierIataCode": "SU"
            }
        },
        "origin": {
            "airportIataCode": origin,
            "terminal": "D",
            "gate": "D12"
        },
        "destination": {
            "airportIataCode": destination
        },
        "localScheduledDepartureDateTime": departure_time,
        "reviewStatus": "UNDER_REVIEW"
    }


def create_flight_object(class_id: str, passenger_name: str,
                         seat: str, booking_ref: str) -> dict:
    object_id = f"YOUR_ISSUER_ID.bp_{booking_ref}"

    return {
        "id": object_id,
        "classId": class_id,
        "state": "ACTIVE",
        "passengerName": passenger_name,
        "boardingAndSeatingInfo": {
            "seatNumber": seat,
            "boardingGroup": "A",
            "seatClass": "ECONOMY"
        },
        "reservationInfo": {
            "confirmationCode": booking_ref,
            "eticketNumber": f"555-{booking_ref}"
        },
        "barcode": {
            "type": "QR_CODE",
            "value": f"M1{passenger_name.upper().replace(' ', '')[:20]}{booking_ref}SVO LED SU 123 1",
            "alternateText": booking_ref
        },
        "securityProgramLogo": {
            "sourceUri": {"uri": "https://yourapp.com/security-badge.png"}
        }
    }

Поле barcode.value — це BCBP-рядок за стандартом IATA, що містить понад 20 полів. Сканери в аеропорту очікують саме цей формат. BCBP генерується на бекенді при створенні FlightObject. Необхідно правильно заповнити всі поля: код авіакомпанії, номер рейсу, маршрут, дату, ім'я пасажира, місце та код бронювання. Помилка в будь-якому полі призводить до відмови сканера. Ми використовуємо перевірену бібліотеку, яка збирає рядок згідно зі специфікацією IATA.

Генерація JWT та збереження на Android

JWT підписується серверним ключем і передається в додаток. Приклад генерації на Python:

def generate_boarding_pass_jwt(flight_object: dict) -> str:
    payload = {
        "iss": service_account_email,
        "aud": "google",
        "typ": "savetowallet",
        "iat": int(time.time()),
        "payload": {
            "flightObjects": [flight_object]
        }
    }
    return jwt.encode(payload, private_key, algorithm="RS256")

На Android викликаємо збереження через SavePassesRequest:

fun saveBoardingPass(jwt: String) {
    val request = SavePassesRequest.newBuilder().setJwt(jwt).build()

    walletClient.savePassesViaIntent(request) { result ->
        result.intentSender?.let { sender ->
            addToWalletLauncher.launch(
                IntentSenderRequest.Builder(sender).build()
            )
        } ?: run {
            showAlreadySaved()
        }
    }
}

Якщо intentSender дорівнює null, пас з таким objectId вже існує — Google не пропонує дублікат. Це нормальна поведінка.

Чому FlightObject кращий за GenericObject?

FlightObject автоматично отримує оновлення рейсу від Google. GenericObject — просто контейнер даних. Порівняння:

FlightObject з автооновленнями підвищує залученість пасажирів у 3 рази порівняно з PDF-посадкою. Наші клієнти відзначають зниження навантаження на підтримку на 40%, що забезпечує значну економію коштів.

Як забезпечити автооновлення рейсу?

Для цього необхідно:

• Статус reviewStatus класу встановити в APPROVED після верифікації issuer.
• Дані рейсу (carrierIataCode, flightNumber, localScheduledDepartureDateTime) повинні точно збігатися з авіабазами.
• Google відстежує статус рейсу за цими полями і надсилає сповіщення без додаткової логіки.

Верифікація issuer — ключовий етап. Вона безкоштовна, але вимагає коректних документів. Ми допомагаємо підготувати їх і пройти процес за 3-5 днів. Економія від автоматичних сповіщень про затримки забезпечує значну економію за рахунок зниження навантаження на call-центр.

Процес та терміни роботи

1. Аналітика — розбираємо структуру додатку, визначаємо точки інтеграції.
2. Проектування — розробляємо схему FlightClass та FlightObject, враховуючи всі поля.
3. Реалізація — пишемо серверну генерацію JWT, додаємо кнопку збереження.
4. Тестування — перевіряємо на тестових пристроях у Google Wallet Console.
5. Деплой — публікуємо оновлення, допомагаємо з верифікацією issuer.

Серверна генерація JWT з BCBP, інтеграція кнопки та тестування займають від 2 днів. Налаштування автооновлень — додатково до 1 дня. Вартість розраховується індивідуально.

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

• Документація API з прикладами на Python і Kotlin.
• Готові класи FlightClass та FlightObject під ваш бренд.
• Інтеграція кнопки «Додати в Google Wallet».
• Налаштування автооновлень статусу рейсу.
• Допомога у верифікації issuer.
• Тестування та підтримка при релізі.
• Навчання співробітників роботі з Google Wallet Console.
• Надання доступів до тестових акаунтів.

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

Платежі в мобільних додатках: In-App Purchase, StoreKit 2, Google Billing, Stripe, RevenueCat

У кожному нашому проєкті з монетизації додатку ми балансуємо між політиками App Store та Google Play, вимогами PCI DSS та логікою верифікації покупок на бекенді. Неправильно зроблена система платежів — це не просто баг, це фінансові втрати та можливий бан додатку. За 7 років ми розібрали понад 50 кейсів інтеграції платіжних SDK — від простої Stripe-форми до розподіленого біллінгу з власними серверними вебхуками.

Як вибрати між In-App Purchase та зовнішнім платіжним шлюзом?

Якщо додаток продає цифровий контент або підписки — Apple та Google вимагають використовувати їхні платіжні системи. Обійти це неможливо: порушення правил 3.1.1 App Store або Google Play Developer Policy призводить до видалення додатку. Фізичні товари та послуги, що надаються офлайн, — інша історія.

In-App Purchase: дві платформи, два різних API

StoreKit 2 (iOS 15+)

StoreKit 2 — повна переробка оригінального StoreKit з async/await API. Product.products(for:), product.purchase(), Transaction.currentEntitlements — читабельно та передбачувано порівняно з чергою транзакцій через SKPaymentTransactionObserver.

Найважливіша зміна: транзакції в StoreKit 2 підписані JWS (JSON Web Signature) і верифікуються локально без серверного roundtrip. Transaction.verificationResult повертає .verified(Transaction) або .unverified(Transaction, VerificationError). Це не означає, що сервер не потрібен — він потрібен для зберігання статусу підписки, але локальна верифікація прибирає затримку при старті.

StoreKit.AppTransaction — верифікація самого факту завантаження додатку з App Store. Потрібна для додатків з платним завантаженням або безстроковими покупками, не підписками.

Складне місце в StoreKit 2 — обробка renewalState для підписок: .subscribed, .expired, .inBillingRetryPeriod, .inGracePeriod, .revoked. Стан inGracePeriod означає, що Apple намагається відновити оплату (до 16 днів) — у цей час потрібно продовжувати надавати доступ. Не обробиш — втратиш лояльних користувачів, у яких тимчасово не пройшла картка. За досвідом, близько 5% підписок потрапляють у billing retry, і автоматичне відновлення доступу повертає до 80% з них.

Google Play Billing Library (v6+)

Google Billing — складніший за StoreKit за кількістю сценаріїв. BillingClient з PurchasesUpdatedListener, queryProductDetailsAsync, launchBillingFlow, queryPurchasesAsync — обов'язково викликати при кожному старті додатку, не покладатися на PurchasesUpdatedListener як єдине джерело правди.

Підтвердження покупки: acknowledgePurchase() для non-consumables та підписок, consumePurchase() для consumables. Якщо не викликати acknowledge протягом 3 днів — Google автоматично зробить повернення. Це гарантована втрата грошей, якщо забути про acknowledge на бекенді після верифікації.

ProductDetails з SubscriptionOfferDetails — в Billing v5+ структура оферт ускладнилася: один продукт може мати кілька basePlanId та offerId (пробний період, знижка для нових користувачів, retention-офер). BillingFlowParams.SubscriptionUpdateParams для апгрейду/даунгрейду підписки з prorationMode.

Чому серверна верифікація обов'язкова?

Ніколи не довіряйте лише клієнтському коду при розблокуванні платного контенту. Клієнтська верифікація обходиться модифікацією додатку.

Для IAP мінімальна схема: додаток отримує receiptData (iOS) або purchaseToken (Android), відправляє на бекенд, бекенд верифікує через Apple App Store Server API / Google Play Developer API, зберігає статус у БД, віддає відповідь клієнту. RevenueCat робить це за вас — але якщо у вас кастомний бекенд, потрібно реалізувати самостійно.

Webhook-и важливіші, ніж здається. Користувач може скасувати підписку через налаштування телефону, не через додаток — додаток не отримає про цю подію в реальному часі. Тільки webhook від Apple/Google (або RevenueCat) дозволяє своєчасно оновити статус. Ми використовуємо перевірку підпису вхідних запитів через Apple's signedPayload та Google's DeveloperNotification.

Як RevenueCat спрощує інтеграцію?

Підтримувати StoreKit 2 та Google Billing одночасно, з урахуванням промо-кодів, оферт, відновлення покупок та серверної верифікації — це кілька місяців розробки. RevenueCat закриває більшу частину цього шару.

RevenueCat — не просто SDK для платежів. Це:

• Єдиний API для iOS та Android (і Stripe для вебу)
• Серверна верифікація та зберігання статусів підписок
• Webhooks на події (покупка, відновлення, скасування, billing issue)
• Аналітика по когортам, MRR, churn
• A/B тестування оферт через Experiments

Purchases.configure(withAPIKey:) при старті, Purchases.shared.getCustomerInfo() для отримання поточних entitlements — мінімальний інтегрований шар. Purchases.shared.purchase(package:) замість прямого виклику StoreKit/Billing.

У документації RevenueCat сказано: «RevenueCat handles receipt validation on the server side, reducing client-side complexity and preventing fraudulent purchases.»

Обмеження RevenueCat: платний (безкоштовно до певного рівня MRR, далі відсоток від доходу), не підходить для дуже складних flow з кількома storefront-ами або кастомними bundle-ами. Однак для типового SaaS-додатку економія на власній розробці є значною — інтеграція окупається швидко.

Stripe в мобільних додатках

Stripe — для оплати фізичних товарів, послуг, B2B-платежів де IAP не вимагається політикою платформи.

Stripe iOS SDK та Android SDK — PaymentSheet для готового UI оплати, PaymentSheetFlowController для кастомного UI зі збереженими картками. Payment Intent створюється на сервері, client secret передається в додаток — карткові дані ніколи не проходять через ваш сервер, лише через Stripe.

Apple Pay та Google Pay через Stripe: PKPaymentRequest (iOS) та GooglePayLauncher (Android) вже інтегровані в Stripe SDK. Конверсія у Apple Pay дає в 1.3–2 рази вищий результат, ніж форми з ручним введенням картки — це цифри, які ми підтвердили на десятці проєктів.

Збережені картки через SetupIntent + Customer API — користувач платить в один тап при повторному візиті. Compliance: PCI DSS SAQ A — найлегший рівень compliance, оскільки Stripe Tokenization прибирає потребу зберігати карткові дані на своїй стороні. Згідно з PCI DSS, передача токенів звільняє від необхідності сертифікації рівня 1.

3DS2 (Strong Customer Authentication) — обов'язковий для платежів у ЄС за PSD2. Stripe обробляє автоматично через PaymentIntent.confirmPayment, але потрібно коректно обробити .requiresAction статус та повернути користувача на потрібний екран після аутентифікації.

Що входить в роботу (deliverables)

Процес та терміни

Починаємо з з'ясування бізнес-моделі: підписки, разові покупки, consumables, freemium. Від цього залежить архітектура. Тестування IAP вимагає Sandbox-акаунтів (Apple) та License Testers (Google) — це окреме налаштування середовища.

Sandbox Apple поводиться не так, як production: підписки відновлюються кожні 5 хвилин замість місяця, inGracePeriod працює по-іншому. Обов'язково тестувати сценарії: закінчення тріалу, скасування, billing retry, refund.

Як налаштувати тестове середовище для платежів?

Вартість розраховується індивідуально виходячи з набору інструментів та складності серверної логіки. У середньому ми вкладаємося в бюджет, який обговорюється окремо, але економія від запобігання помилок та churn окупає ці вкладення за 2–3 місяці.

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