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

На чтение
10 мин
Дата обновления
05.11.2026

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, который чаще всего встречается в первой интеграции и старых туториалах.

Тип сообщенияForegroundBackground
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.

  1. Сначала отправьте простое notification-сообщение с заголовком и текстом.
  2. Проверьте его в foreground и в background.
  3. Если используете 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 и более сложной логике.