Інтеграція 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-сповіщень для будь-якого сценарію.