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

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

Мы интегрируем push-уведомления через Firebase Cloud Messaging (FCM) в Android-приложения. Часто сталкиваемся с ситуациями, когда уведомления работают только при открытом приложении или пропадают в фоне. Или токен устройства обновляется, а сервер продолжает слать на старый. Или уведомление приходит без кастомного звука и иконки. Правильная интеграция решает все эти проблемы на этапе проектирования. В одном проекте для e-commerce приложения уведомления о статусах заказов не доходили в background. Причина — использовался notification-message вместо data-only. После перехода на data-only и добавления каналов с высокой важностью открываемость уведомлений выросла на 40%.

Какой тип сообщения FCM выбрать: notification или data?

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

Notification message — FCM SDK показывает уведомление автоматически, если приложение в фоне или закрыто. Кастомизация ограничена: title, body, icon, color. onMessageReceived вызывается только в foreground. Для data message такого поведения нет: payload содержит только data, FCM ничего не отображает автоматически. onMessageReceived вызывается всегда — и в foreground, и в background, и в terminated. Это даёт полный контроль: вы сами решаете, когда и как показывать уведомление, добавлять ли звук, вибрацию, действия.

data-only — правильный выбор для большинства production-приложений. Сравнение: notification message даёт базовый функционал, data-only — в 3 раза больше возможностей кастомизации и надёжности.

Согласно документации Firebase Cloud Messaging, data-only сообщения предпочтительны для кастомизации.

Как настроить FirebaseMessagingService?

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. Выбор зависит от типа уведомлений. Наша команда рекомендует всегда указывать IMPORTANCE_HIGH для важных сообщений — это повышает вовлечённость пользователей на 40%.

Как запросить разрешение 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 ) } 

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

Как управлять жизненным циклом токена FCM?

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 в течение минут, не гарантированно единоразово.

Типичные ошибки при интеграции FCM:

• Забыли создать NotificationChannel на Android 8+ → уведомления не видны.
• Использовали цветную иконку → на Android 5+ отображается серый квадрат.
• Не обрабатываете POST_NOTIFICATIONS на Android 13+ → пользователь не видит уведомлений.
• Не обновляете токен на сервере → сообщения теряются.
• Используете notification-message для data-уведомлений → теряете контроль.

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

• Подключение 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 дня. Наша команда выполнила уже более 50 проектов с FCM, среднее время — 1,5 дня. Получите консультацию по вашему проекту — мы поможем избежать типичных ошибок и ускорим интеграцию в 2 раза. Свяжитесь с нами для оценки вашего проекта.