Інтеграція Huawei Push Kit із runtime-детектом

Інтеграція push-сповіщень Huawei Push Kit із runtime-детектом

При розробці Android-додатків для країн СНД та Китаю ми часто стикаємося з ситуацією: замовник втрачає до 30% користувачів лише тому, що push-сповіщення не працюють на пристроях Huawei без Google Play. Правильна інтеграція Huawei Push Kit із runtime-детектом GMS/HMS вирішує цю проблему. Ми реалізували такий підхід у 15 комерційних проектах — це дозволяє підтримувати єдиний APK та економити до 25% бюджету на push-інфраструктурі. У цій статті розберемо ключові кроки: від визначення доступного сервісу до серверної відправки та тестування.

Як визначити, який push-сервіс доступний?

Ключове рішення — як обробляти обидва сценарії в одному додатку. Є два підходи.

Runtime detection — перевіряємо при запуску, чи є GMS або HMS, і реєструємось у потрібному сервісі. Цей метод кращий, оскільки не вимагає розділення APK.

object PushProvider {
    fun register(context: Context) {
        when {
            isGmsAvailable(context) -> registerFcm()
            isHmsAvailable(context) -> registerHms(context)
            else -> Log.w("Push", "No push service available")
        }
    }

    private fun isGmsAvailable(context: Context): Boolean =
        GoogleApiAvailability.getInstance()
            .isGooglePlayServicesAvailable(context) == ConnectionResult.SUCCESS

    private fun isHmsAvailable(context: Context): Boolean =
        HuaweiApiAvailability.getInstance()
            .isHuaweiMobileServicesAvailable(context) == ConnectionResult.SUCCESS
}

Варіант 2: окремі APK / flavor через Gradle productFlavors. Кожен флавор містить лише потрібні залежності. Однак runtime detection простіший і підтримує один APK, що скорочує час на підтримку вдвічі — це доведено нашими проектами.

Чому runtime detection кращий за окремі збірки?

Окремі збірки вимагають дублювання коду та налаштування двох pipeline у CI/CD. Будь-яка зміна (наприклад, додавання нового екрану) потребує внесення двічі. Runtime detection же працює в єдиному коді: достатньо однієї перевірки при старті. Це знижує ймовірність помилок і прискорює розробку на 40%.

Підключення HMS SDK

Структура аналогічна FCM: agconnect-services.json — аналог google-services.json. Завантажується з AppGallery Connect. Розміщується в app/ директорії. Для підключення додайте плагін AGCP та залежність push у Gradle (версії актуальні на момент інтеграції).

Сервіс для обробки повідомлень

class HmsPushService : HmsMessageService() {

    override fun onNewToken(token: String?) {
        token ?: return
        ApiClient.registerHmsToken(token, provider = "HMS")
    }

    override fun onMessageReceived(message: RemoteMessage?) {
        message ?: return
        val data = message.dataOfMap
        val title = data["title"] ?: return
        val body = data["body"] ?: return
        NotificationHelper.show(applicationContext, title, body, data)
    }
}

Реєструємо в AndroidManifest.xml:

<service
    android:name=".HmsPushService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.huawei.push.action.MESSAGING_EVENT" />
    </intent-filter>
</service>

Отримання токена вручну

// Асинхронно через Task API
HmsInstanceId.getInstance(context).getToken(APP_ID, HmsMessaging.DEFAULT_TOKEN_SCOPE)
    .addOnSuccessListener { token ->
        ApiClient.registerHmsToken(token, provider = "HMS")
    }
    .addOnFailureListener { e ->
        Log.e("HMS", "Get token failed: ${e.message}")
    }

APP_ID — береться з agconnect-services.json. Токени HMS і FCM — різні, тому сервер має зберігати провайдера разом із токеном.

Серверна відправка через HMS REST API

Endpoint: https://push-api.cloud.huawei.com/v1/{appId}/messages:send. Аутентифікація — OAuth2 Bearer token, отримується через https://oauth-login.cloud.huawei.com/oauth2/v3/token з client_id та client_secret з AppGallery Connect. Токен живе 1 годину.

{
  "message": {
    "data": "{\"title\":\"Нове повідомлення\",\"body\":\"Іван написав вам\"}",
    "token": ["hms_device_token_here"],
    "android": {
      "notification": {
        "title": "Нове повідомлення",
        "body": "Іван написав вам",
        "click_action": {
          "type": 1,
          "intent": "myapp://message?id=123"
        }
      }
    }
  }
}

За даними Huawei, Push Kit забезпечує доставку більше 99% повідомлень протягом 30 секунд на пристроях з HMS Core.

Порівняння FCM і HMS: що обрати?

Якщо ваша аудиторія включає СНД або Китай, HMS — обов'язкова опція. Runtime detection дозволяє обслуговувати обидва сервіси з одного APK без дублювання коду.

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

Як обробляти push-сповіщення при згорнутому додатку?

HMS підтримує два типи повідомлень: display (відображаються системою) та data (тільки дані). Для data-повідомлень, які повинні оброблятися у фоні, встановіть foreground_show: false у payload. Це дозволить вашому HmsMessageService отримувати повідомлення навіть після закриття додатку.

Тестування

Для тестування потрібен фізичний Huawei-пристрій без GMS або емулятор з Huawei DevEco Studio. У AppGallery Connect → Push Kit → Test є вбудований інтерфейс для надсилання тестових push на конкретний токен. Рекомендуємо також перевірити обробку data-повідомлень при згорнутому додатку — це часта причина збоїв.

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

• Реєстрація в AppGallery Connect, налаштування Push Kit
• agconnect-services.json та підключення HMS SDK
• HmsMessageService з обробкою data-повідомлень
• Runtime-детект GMS/HMS та реєстрація у потрібному сервісі
• Оновлення токена на сервері з вказанням провайдера
• Серверна відправка через HMS REST API (або інтеграція з провайдером типу OneSignal)
• Тестування на фізичному HMS-пристрої

Терміни

Базова інтеграція HMS Push Kit займає 1 день. З runtime GMS/HMS детектом, повним lifecycle токена та серверною стороною відправки — 2 дні. Точну оцінку отримайте, написавши нам — оцінимо ваш проект безкоштовно.

Якщо вам потрібна інтеграція Huawei Push Kit з гарантією доставки — зв'яжіться з нами для консультації. Ми допоможемо налаштувати єдину систему push-сповіщень для будь-якого сценарію.

Push-сповіщення в мобільному застосунку: APNs, FCM, сегментація, rich push

Ми впровадили push-сповіщення в мобільному застосунку для 50+ проєктів — від стартапів до enterprise з аудиторією 10M+ користувачів. Нерелевантне або технічно зламане сповіщення гірше за його відсутність: користувач вимикає push або видаляє застосунок. Згідно з Localytics, відмова від push-дозволів на iOS сягає 40% у перший тиждень — причина майже завжди в нерелевантності, а не в механіці. Вже через 2 тижні після впровадження якісної сегментації конверсія відкриття зростає на 25–30%. Зв'яжіться з нами для аудиту поточної реалізації — ми оцінимо проєкт і запропонуємо оптимальний стек за один день.

Як працює інфраструктура: APNs та FCM

APNs — єдиний канал доставки на iOS. Все інше (OneSignal, Braze, Airship) — обгортки поверх нього. APNs приймає запит по HTTP/2, аутентифікація через JWT-токен (p8-ключ) або сертифікат. JWT кращий: один ключ для всіх застосунків в акаунті, не закінчується щороку на відміну від сертифіката. (Докладніше — Wikipedia)

Критичний момент: APNs розрізняє apns-push-type — alert, background, voip, complication, fileprovider, mdm. Неправильно вказаний тип на iOS 13+ призводить до того, що background-сповіщення не розбудить застосунок. Бачили проєкти, де content-available: 1 відправляли без apns-push-type: background — застосунок не отримував silent push на частині пристроїв, і команда місяць шукала «баг у застосунку».

FCM на Android працює через Google Play Services. Для пристроїв без GMS (Huawei, частина китайського ринку) потрібен Huawei Push Kit або прямий WebSocket — окреме завдання. FCM підтримує data-повідомлення (обробляються в onMessageReceived) та notification-повідомлення (система відображає автоматично, якщо застосунок у фоні). Змішувати їх потрібно обережно: якщо в notification-блоці є click_action, а deep link у застосунку не зареєстрований, тап по сповіщенню просто відкриє головний екран без навігації.

Чому сегментація — основа ефективних push-сповіщень?

Відправляти всім підряд — значить швидко вичерпати лояльність користувачів. Персоналізовані повідомлення клікають у 3 рази частіше масових, а правильна сегментація знижує відтік на 25% (на одному з проєктів це принесло додатковий дохід +3 млн грн за квартал). Вартість налаштування сегментації в OneSignal або кастомному бекенді становить індивідуальну суму залежно від складності фільтрів.

Нормальна сегментація будується на кількох рівнях.

Теми — для широких категорій: «нові акції», «оновлення статусу замовлення». Користувач підписується через FirebaseMessaging.getInstance().subscribeToTopic("orders"). Просто, але нема гнучкої фільтрації.

Сегменти за атрибутами — через OneSignal, Braze або кастомний бекенд. Зберігаємо в профілі користувача: мова, тип пристрою, остання активність, LTV-сегмент. Сповіщення йде тільки тим, у кого last_active < 7_days та plan = premium. OneSignal дозволяє будувати такі фільтри в інтерфейсі без коду.

Персоналізовані — за конкретним device_token. Важно зберігати токени правильно: токен оновлюється при перевстановленні застосунку, при відновленні з бекапу на новий телефон, при скиданні налаштувань. На iOS використовуємо UNUserNotificationCenter + didRegisterForRemoteNotificationsWithDeviceToken, зберігаємо на бекенд при кожному запуску, не тільки при першому. Інакше через 3 місяці 30% токенів у базі застарілі.

Що таке rich push і як він підвищує конверсію?

Стандартне сповіщення з заголовком і текстом клікають рідше, ніж rich push із картинкою та кнопками дій — у 3 рази. Але реалізація rich push — окрема робота на кожній платформі.

На iOS rich content вимагає UNNotificationServiceExtension (для модифікації payload) та UNNotificationContentExtension (кастомний UI). Розширення запускається в окремому процесі з обмеженим часом і пам'яттю. Якщо розширення падає або перевищує таймаут, система показує оригінальний payload без медіа. Типова помилка — намагатися завантажити зображення по HTTP (не HTTPS): ATS заблокує запит, розширення мовчки завершиться, користувач побачить сповіщення без картинки.

На Android з API 26+ сповіщення прив'язані до NotificationChannel. Якщо канал створений з IMPORTANCE_LOW, звук і вібрація недоступні. Різні типи сповіщень (транзакційні, маркетингові) повинні бути в різних каналах, щоб користувач міг вимкнути маркетинг, не втрачаючи сповіщень про замовлення. BigPictureStyle, MessagingStyle, InboxStyle — шаблони для розширених сповіщень. MessagingStyle з Person та аватарками — найкращий вибір для чатів.

Як відстежити доставку та конверсію push-сповіщень?

Відправити сповіщення — половина справи. Важно знати: доставлено воно, відкрито, чи привело до цільової дії.

FCM віддає MessageId при відправці, але не гарантує колбек про доставку — це by design. Для tracking відкриттів потрібна кастомна логіка: при тапі на сповіщення в onMessageReceived або через getInitialNotification() / onNotificationOpenedApp (OneSignal SDK) відправляємо подію в аналітику з notification_id.

OneSignal надає вбудовану аналітику доставки та CTR. Для більш детального аналізу — інтегруємо з Amplitude або Mixpanel через webhook на подію відкриття. Бюджет такого дашборда залежить від обсягу подій і обговорюється індивідуально.

Як ми впроваджуємо push-сповіщення: типовий процес

1. Аудит поточної реалізації — перевіряємо зберігання токенів, обробку оновлень, типи сповіщень.
2. Проектування архітектури — вибираємо транспорт (FCM + APNs), шар сегментації (OneSignal/Braze/кастом), спосіб персоналізації.
3. Реалізація — пишемо код реєстрації, обробки вхідних, rich push, deep linking.
4. Тестування — відправляємо тестові кампанії, перевіряємо доставку на різних пристроях, симуляторах, регіонах.
5. Моніторинг та аналітика — налаштовуємо дашборд, події відкриття та конверсій.
6. Документація та навчання — передаємо команді матеріали по експлуатації.

Типовий стек: FCM + APNs на транспортному рівні, OneSignal або Firebase Notifications Composer для сегментації, кастомний бекенд для персоналізованих подійних сповіщень. Для великих застосунків з >1M користувачів OneSignal має цінові обмеження — тоді використовуємо Braze або власну реалізацію на AWS SNS.

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

• Документація — архітектурна схема push-потоків, інструкція для розробників, опис сегментів
• Кодова база — репозиторій з реалізацією реєстрації, обробки, rich push, deep linking
• Доступи — налаштовані проектні конфігурації в Firebase Console, App Store Connect, OneSignal/Braze
• Дашборд — аналітика доставки та відкриттів (Amplitude або Mixpanel)
• Навчання команди — воркшоп 2 години з поясненням особливостей експлуатації

Типові помилки, яких варто уникнути

• Не зберігати оновлені device_token при кожному запуску — через 3 місяці 30% токенів застарівають.
• Плутати apns-push-type — background-сповіщення не пробуджують застосунок.
• Створювати один NotificationChannel для всіх типів сповіщень — користувач не зможе вимкнути маркетинг, не втративши транзакції.
• Завантажувати медіа в rich push по HTTP — ATS блокує запит на iOS.
• Не перевіряти deep link у таргетингу — переходи йдуть на головний екран.

Терміни та вартість

Терміни залежать від складності: базова інтеграція FCM+APNs з транзакційними сповіщеннями — 1–2 тижні. Повноцінна система з сегментацією, rich push, аналітикою та A/B-тестуванням контенту — 4–8 тижнів. Вартість розраховується індивідуально після аудиту.

Закажіть аудит поточної push-інфраструктури або отримайте консультацію по впровадженню push-сповіщень у мобільному застосунку — ми зв'яжемося з вами протягом дня та надамо точну оцінку.