Как подключить Firebase Cloud Messaging в Android-приложении на Kotlin

Firebase Cloud Messaging, или FCM, — стандартный способ добавить push-уведомления в Android-приложение без собственной инфраструктуры доставки. Для первой интеграции он удобен тем, что Firebase берет на себя регистрацию клиента, доставку сообщений и базовую работу с уведомлениями, а от приложения требуется корректно подключить SDK и обработать входящие события.
Ниже — практическая настройка с нуля: регистрация Android-приложения в Firebase, подключение google-services.json и зависимостей, реализация FirebaseMessagingService, разбор поведения notification и data payload, настройка канала уведомлений и проверка через тестовое сообщение из Firebase Console.
Когда FCM подходит для первой интеграции
FCM обычно выбирают для сервисных и пользовательских уведомлений: новых сообщений, статусов заказа, напоминаний, новостей, событий аккаунта. Для старта это хороший вариант по двум причинам.
- Есть быстрый путь проверки: можно отправить тестовое уведомление прямо из Firebase Console.
- Есть путь к более гибкой логике: кроме обычных notification-сообщений, FCM поддерживает data messages, где приложение само решает, что делать с полезной нагрузкой.
Для клиентской части нужны Android 7.0+ и устройство или эмулятор с Google Play services. На эмуляторе без Google APIs приложение может собраться и запуститься, но push не придет.
Подготовка проекта в Firebase
Сначала создайте проект в Firebase Console и добавьте в него Android-приложение. Самое важное поле на этом шаге — package name, то есть applicationId вашего app-модуля. Значение должно совпадать полностью, включая регистр символов.
Это не формальность. Плагин Google services читает google-services.json, ищет в нем клиент с подходящим package name и генерирует ресурсы для приложения. Если package name в Firebase и в Gradle не совпадает, сборка может завершиться ошибкой, а иногда приложение подключится не к той конфигурации, которую вы ожидали.
После регистрации скачайте файл google-services.json и положите его в корень app-модуля:
MyProject/
app/
google-services.jsonДля проекта с flavor и разными build type можно хранить отдельные файлы по вариантам сборки, но для первой интеграции обычно достаточно одного общего файла в app/.
Настройка Gradle: plugin, BoM и firebase-messaging
Дальше нужно подключить Google services plugin и зависимость Firebase Messaging. Удобнее использовать Firebase Android BoM: он синхронизирует версии Firebase-библиотек между собой.
Корневой build.gradle.kts
Ниже показаны добавления к работающему Android-проекту на Kotlin, а не полная замена Gradle-файлов. Сохраните совместимые настройки Android, Kotlin и SDK вашего проекта.
plugins {
id("com.google.gms.google-services") version "4.5.0" apply false
}app/build.gradle.kts
plugins {
id("com.google.gms.google-services")
}
dependencies {
implementation(platform("com.google.firebase:firebase-bom:35.1.0"))
implementation("com.google.firebase:firebase-messaging")
}Здесь роли распределяются так:
- Google services plugin обрабатывает
google-services.json. - Firebase Android BoM задает согласованные версии библиотек Firebase.
- firebase-messaging добавляет SDK для приема и обработки push-сообщений.
Если сборка сообщает, что google-services.json не найден, почти всегда проблема в одном из двух мест: файл лежит не в app-модуле или плагин com.google.gms.google-services применен не там, где находится этот файл.
FirebaseMessagingService: что реализовать в Kotlin
Для приема сообщений нужен сервис, наследующий FirebaseMessagingService. Его необходимо зарегистрировать в манифесте:
<application android:name=".App">
<service
android:name=".MyFirebaseMessagingService"
android:exported="false">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter>
</service>
</application>Базовая реализация выглядит так:
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage
class MyFirebaseMessagingService : FirebaseMessagingService() {
override fun onNewToken(token: String) {
super.onNewToken(token)
android.util.Log.d("FCM", "Registration token: $token")
// Если у вас есть сервер, сюда обычно отправляют токен.
}
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
android.util.Log.d("FCM", "From: ${remoteMessage.from}")
if (remoteMessage.data.isNotEmpty()) {
android.util.Log.d("FCM", "Data payload: ${remoteMessage.data}")
}
remoteMessage.notification?.let {
android.util.Log.d("FCM", "Notification body: ${it.body}")
}
}
}onMessageReceived — основной колбэк для входящих сообщений в типовом клиентском сценарии первой интеграции. Внутри него удобно разбирать данные, решать, нужен ли показ локального уведомления, и запускать короткую прикладную логику.
Важно, что у этого обработчика короткое окно выполнения. Если внутри него делать долгую работу — например, сетевой запрос за изображением или тяжелую синхронизацию, — итоговое уведомление может задержаться. Для задач дольше нескольких секунд безопаснее передавать работу в WorkManager.
Что учитывать с token и FID
В новых материалах Firebase есть переход от старой схемы с registration token к регистрации экземпляра приложения через Firebase Installation ID, или FID. Поэтому в документации можно встретить сразу две линии API.
Для первой интеграции и проверки через Firebase Console по-прежнему часто используют onNewToken и получение текущего токена. Это удобно, потому что тестовое сообщение в консоли отправляют именно на token.
FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
if (!task.isSuccessful) return@addOnCompleteListener
android.util.Log.d("FCM", "Current token: ${task.result}")
}Если же вы строите серверную адресацию по актуальной модели Firebase, можно включить регистрацию через FID в манифесте:
<meta-data
android:name="firebase_messaging_installation_id_enabled"
android:value="true" />После этого используют регистрацию экземпляра и callback onRegistered для отправки идентификатора на свой сервер. Практический смысл простой: для первого рабочего push достаточно корректно подключить Messaging и реализовать прием сообщений, а выбор между token и FID становится важнее, когда появляется собственная серверная отправка и хранение идентификаторов устройств.
Как ведут себя notification, data и mixed messages
Частая причина путаницы — ожидание, что все типы сообщений ведут себя одинаково. На деле поведение зависит от payload и от того, открыто приложение или нет.
Ниже приведена таблица для legacy AndroidConfig (v1) — именно к этой модели относится привычный разбор через onMessageReceived, который чаще всего встречается в первой интеграции и старых туториалах.
| Тип сообщения | Foreground | Background |
|---|---|---|
| Notification | Приходит в onMessageReceived, поведение определяет код приложения | Система показывает уведомление в шторке |
| Data | Приходит в onMessageReceived | Приходит в onMessageReceived |
| Notification + Data | Оба payload доступны в onMessageReceived | Уведомление показывает система, а data попадает в extras при открытии приложения по тапу |
Это не универсальное правило для всех современных способов отправки. В актуальной документации Firebase отдельно оговорено, что для AndroidConfigV2 и RemoteNotification маршрутизация user-visible уведомлений описывается иначе: такие уведомления доставляются автоматически и в foreground, и в background, если вы специально не подавляете их показ в клиентском коде.
Для первой интеграции из этой разницы полезно вынести три вывода:
- Если вы проверяете типовой сценарий через привычный
onMessageReceived, ориентируйтесь на поведение legacy AndroidConfig (v1). - Если серверная часть позже перейдет на AndroidConfigV2 с RemoteNotification, перепроверьте клиентскую логику показа уведомлений: часть ожиданий из старых таблиц перестанет быть точной.
- Сообщения из Firebase Console удобны для проверки базовой доставки и отображения, но они не заменяют полноценный серверный сценарий для всех вариантов payload.
Типичное затруднение новичка выглядит так: push «пришел», потому что вы видите лог в onMessageReceived, но пользователь ничего не видит на экране. Для foreground-сценария в legacy-модели это нормально: открытое приложение само решает, показывать ли локальное уведомление.
Notification channel и разрешение на уведомления
Начиная с Android 8.0, уведомления должны быть привязаны к каналу. Для первой интеграции лучше создать хотя бы один канал при старте приложения.
class App : android.app.Application() {
override fun onCreate() {
super.onCreate()
createNotificationChannel()
}
private fun createNotificationChannel() {
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
val channel = android.app.NotificationChannel(
"default_channel",
"General notifications",
android.app.NotificationManager.IMPORTANCE_DEFAULT
)
val manager = getSystemService(android.app.NotificationManager::class.java)
manager.createNotificationChannel(channel)
}
}
}Класс App нужно зарегистрировать через android:name=".App" у существующего элемента application в AndroidManifest.xml. Если свой Application уже есть, перенесите создание канала в его onCreate.
Чтобы FCM использовал этот канал для notification-сообщений по умолчанию, укажите его ID в манифесте:
<meta-data
android:name="com.google.firebase.messaging.default_notification_channel_id"
android:value="default_channel" />Иконку по умолчанию тоже можно задать в манифесте. Ресурс в примере условный: нужен существующий drawable.
<meta-data
android:name="com.google.firebase.messaging.default_notification_icon"
android:resource="@drawable/ic_stat_notification" />На Android 13+ этого недостаточно: нужно еще получить у пользователя runtime-разрешение POST_NOTIFICATIONS. Без него FCM может принять сообщение, но системное уведомление не появится.
Разрешение объявляют в AndroidManifest.xml внутри manifest, до application:
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />И запрашивают в Activity:
private val notificationPermission = registerForActivityResult(
androidx.activity.result.contract.ActivityResultContracts.RequestPermission()
) { granted ->
android.util.Log.d("FCM", "Notifications allowed: $granted")
}
private fun requestNotificationsIfNeeded() {
if (android.os.Build.VERSION.SDK_INT >= 33 &&
androidx.core.content.ContextCompat.checkSelfPermission(
this, android.Manifest.permission.POST_NOTIFICATIONS
) != android.content.pm.PackageManager.PERMISSION_GRANTED
) {
notificationPermission.launch(android.Manifest.permission.POST_NOTIFICATIONS)
}
}Для первой интеграции безопасное правило такое: создайте канал заранее и запросите разрешение на уведомления до тестовой отправки.
Как проверить интеграцию через Firebase Console
После настройки запустите приложение на устройстве, убедитесь, что сборка проходит без ошибок Firebase, и отправьте тестовое сообщение из Firebase Console.
- Сначала отправьте простое notification-сообщение с заголовком и текстом.
- Проверьте его в foreground и в background.
- Если используете mixed message, отдельно проверьте, как приложение получает data-часть.
Если базовый тест не сработал, пройдитесь по короткому списку:
- package name в Firebase точно совпадает с
applicationId; google-services.jsonлежит вapp/;- подключен
com.google.gms.google-services; - добавлена зависимость
firebase-messaging; MyFirebaseMessagingServiceобъявлен в манифесте;- тест идет на устройстве или эмуляторе с Google Play services;
- на Android 13+ выдано
POST_NOTIFICATIONS; - создан notification channel и его ID совпадает с тем, что указан в metadata;
- вы не переносите без проверки таблицу поведения legacy AndroidConfig (v1) на сценарий AndroidConfigV2.
Минимальная рабочая схема выглядит так: зарегистрировать Android app в Firebase, положить google-services.json в app-модуль, подключить плагин и firebase-messaging, добавить FirebaseMessagingService, создать notification channel, запросить разрешение на уведомления и проверить доставку через Firebase Console. Этого достаточно, чтобы получить первый работающий push в Android-приложении на Kotlin и потом переходить к серверной отправке, topics и более сложной логике.




