Интеграция push-уведомлений через Firebase Cloud Messaging (FCM)

Интеграция push-уведомлений через Firebase Cloud Messaging (FCM)

FCM — стандарт push-уведомлений для Android. Но «добавить Firebase» и «правильно интегрировать FCM» — разные вещи. Типичные проблемы: уведомления приходят, когда приложение открыто, и пропадают в background. Или приходят, но без кастомного звука и иконки. Или токен обновляется, а сервер об этом не знает.

Типы сообщений FCM: notification vs data

Это различие критично и часто понимается неправильно.

Notification message (display message): FCM SDK показывает уведомление автоматически, когда приложение в background/terminated. Кастомизация ограничена — только title, body, icon, color. onMessageReceived в foreground вызывается, в background — нет.

Data message: payload содержит только data без блока notification. FCM не показывает ничего автоматически. onMessageReceived вызывается всегда — и в foreground, и в background, и в terminated (через FirebaseMessagingService). Полный контроль над отображением.

Для большинства реальных приложений правильный выбор — data-only с ручным построением уведомления в onMessageReceived.

Настройка сервиса

class PushMessagingService : FirebaseMessagingService() {

    override fun onNewToken(token: String) {
        // Отправить token на сервер
        ApiClient.registerFcmToken(token)
    }

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

    private fun showNotification(title: String, body: String, data: Map<String, String>) {
        val channelId = "default_channel"
        val intent = Intent(this, MainActivity::class.java).apply {
            flags = Intent.FLAG_ACTIVITY_SINGLE_TOP
            putExtra("payload", data.toString())
        }
        val pendingIntent = PendingIntent.getActivity(
            this, 0, intent,
            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
        )

        val notification = NotificationCompat.Builder(this, channelId)
            .setSmallIcon(R.drawable.ic_notification) // Важно: белая иконка на прозрачном фоне
            .setContentTitle(title)
            .setContentText(body)
            .setAutoCancel(true)
            .setContentIntent(pendingIntent)
            .build()

        NotificationManagerCompat.from(this).notify(System.currentTimeMillis().toInt(), notification)
    }
}

ic_notification — белая монохромная иконка 24dp. Если передать цветную — Android 5+ покажет серый квадрат вместо иконки. Это самая частая визуальная ошибка.

Notification Channels (Android 8+)

Без канала уведомление не покажется на Android 8+. Канал создаётся один раз при запуске:

fun createNotificationChannel(context: Context) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        val channel = NotificationChannel(
            "default_channel",
            "Основные уведомления",
            NotificationManager.IMPORTANCE_HIGH
        ).apply {
            description = "Сообщения и обновления"
            enableLights(true)
            lightColor = Color.BLUE
            enableVibration(true)
        }
        context.getSystemService(NotificationManager::class.java)
            ?.createNotificationChannel(channel)
    }
}

IMPORTANCE_HIGH — уведомление с звуком и heads-up. IMPORTANCE_DEFAULT — без heads-up. Выбор зависит от типа уведомлений.

Разрешение POST_NOTIFICATIONS (Android 13+)

// Android 13+ требует явного разрешения
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    ActivityCompat.requestPermissions(
        activity,
        arrayOf(Manifest.permission.POST_NOTIFICATIONS),
        REQUEST_CODE_NOTIFICATIONS
    )
}

Запрашиваем в нужный момент контекста — не при первом запуске приложения, а когда пользователь включает нотификации в настройках.

Жизненный цикл токена

onNewToken вызывается при первой регистрации и при обновлении токена (переустановка, очистка данных, обновление Google Play Services). Токен нужно всегда сохранять на сервер. При отправке на устаревший токен FCM возвращает INVALID_REGISTRATION или NOT_REGISTERED — сервер должен удалять такие токены.

Получить текущий токен вручную:

FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val token = task.result
        // Отправляем на сервер при каждом запуске (для надёжности)
    }
}

Теги и подписки на топики

Для широковещательных уведомлений (всем пользователям или группе) — FCM Topics:

FirebaseMessaging.getInstance().subscribeToTopic("news")
    .addOnCompleteListener { task ->
        if (task.isSuccessful) Log.d("FCM", "Subscribed to news topic")
    }

Отправка на топик на сервере: "to": "/topics/news". Delivery в течение минут, не гарантированно единоразово.

Что входит в работу

• Подключение Firebase SDK, google-services.json
• FirebaseMessagingService с data-message обработкой
• Notification Channels с правильными параметрами
• Белая иконка уведомления
• Запрос разрешения POST_NOTIFICATIONS на Android 13+
• Lifecycle токена с обновлением на сервере
• Обработка tap на уведомление: навигация к нужному экрану
• Topics для групповых уведомлений

Сроки

Базовая интеграция FCM с alert-уведомлениями: 1 день. С data-message обработкой, кастомными каналами, навигацией по payload и lifecycle токена: 1,5–2 дня.