Интеграция Firebase Cloud Messaging с Delphi под Android

Push-уведомления давно стали стандартным каналом взаимодействия с пользователями мобильных приложений, и для разработчиков на Delphi эта задача вполне решаема благодаря прямому доступу к Android API. Firebase Cloud Messaging от Google остаётся одним из самых удобных и масштабируемых сервисов доставки сообщений, работающим как с фоновыми, так и с приоритетными push-кампаниями. При правильной настройке можно организовать полный цикл — от регистрации устройства до обработки пользовательских действий по нажатию на уведомление.

В материале разобраны ключевые шаги интеграции: подготовка проекта в консоли Firebase, подключение сервисов Google к Android-приложению, получение регистрационного токена, приём и разбор payload, а также отправка тестовых сообщений через REST API. Отдельно рассмотрены нюансы, связанные с фоновыми сервисами FireMonkey и поведением приложения в свёрнутом состоянии.

Создание проекта в консоли Firebase

Прежде чем подключать FCM к мобильному клиенту, необходимо завести проект в Firebase Console и зарегистрировать в нём Android-приложение с тем же package name, который задан в настройках проекта RAD Studio. После создания проекта в консоли добавляется Android-приложение, где указывается имя пакета, псевдоним и сертификат SHA-1 отладочного ключа. Этих данных достаточно, чтобы Firebase сгенерировал файл конфигурации google-services.json.

Полученный JSON-файл нужно положить в нужную папку проекта и убедиться, что его содержимое корректно объединяется с манифестом Android при сборке. В FMX-проектах Delphi это делается через специальный провайдер сервисов, который занимается инициализацией Firebase автоматически. Если конфигурация отсутствует или повреждена, попытка вызвать FCM API вернёт исключение с кодом ошибки уже на этапе получения токена.

Подключение зависимостей в проекте Delphi

Чтобы код Delphi смог обращаться к классам Firebase Messaging, в проект добавляются библиотеки Firebase Common, Firebase Messaging и сервисы Google Play. Эти зависимости описываются в манифесте через специальный файл с декларацией метаданных и интента. На этапе сборки RAD Studio считывает зависимости и формирует итоговый AndroidManifest.xml, в котором появляются нужные разрешения и компоненты.

Параллельно в коде Delphi пишется обёртка над Android-интерфейсами через JNI-мост или подключается сторонняя библиотека, предоставляющая удобный API на Object Pascal. Такой подход позволяет вызывать Java-методы напрямую из FMX-приложения без необходимости писать собственные модули на Kotlin. Главное при этом — корректно зарегистрировать IntentFilter, который принимает входящие сообщения, иначе приложение просто не получит данные при свёрнутом состоянии.

Получение регистрационного токена

Каждое устройство, на котором установлено приложение с подключённым FCM, получает уникальный токен — длинную строку, идентифицирующую установку. Этот идентификатор необходим серверной части, чтобы знать, кому именно отправлять push-сообщение. В Delphi код получения токена обычно вызывается сразу после успешной инициализации Firebase и сохраняется в локальной памяти либо передаётся на бэкенд разработчика.

Токен принято получать асинхронно, так как запрос к серверам Google может занимать сотни миллисекунд. Если сразу использовать синхронный вызов, интерфейс приложения рискует зависнуть на старте. При работе в эмуляторе без Google Play Services получить токен невозможно — приложение вернёт ошибку SERVICE_NOT_AVAILABLE, поэтому отладку push-логики лучше проводить на реальном устройстве или в эмуляторе с предустановленными сервисами Google.

Обработка входящих сообщений

Push-сообщение состоит из двух частей — уведомления и данных. Первая управляется системой Android и отображается в шторке автоматически, даже если приложение свёрнуто. Вторая часть содержит произвольный JSON-payload, который приложение получает и обрабатывает по своей логике. Именно через data-блок удобно передавать идентификаторы событий, ссылки на внутренние экраны или команды для клиента.

В Delphi обработчик входящего сообщения реализуется как отдельный сервис, подписанный на соответствующий Intent. При получении данных он парсит JSON, достаёт нужные поля и выполняет бизнес-логику: обновляет интерфейс, кладёт запись в локальную базу, отправляет аналитику. Если приложение в момент доставки не запущено, Android сам поднимет процесс и вызовет зарегистрированный сервис, поэтому важно реализовать его с учётом быстрого старта без тяжёлых операций инициализации.

Отправка сообщений через REST API

Для отправки push из серверной части используется Firebase HTTP API с server key, который выдаётся в настройках проекта. Запрос представляет собой POST на адрес fcm.googleapis.com с заголовком Authorization и телом в формате JSON. Минимальный payload содержит массив registration_ids или поле to с конкретным токеном, а также объекты notification и data.

Серверная часть приложения может быть написана на любом стеке — PHP, Node.js, Go, — но в проектах Delphi часто встречается связка RAD Server с DataSnap, где эндпоинт для отправки уведомлений добавляется в общий каталоге решений разработчика и доступен другим модулям. При отправке важно помнить, что устаревший HTTP endpoint постепенно заменяется новым v1 API на основе OAuth2, и при миграции структура запроса меняется существенно.

Фоновые сервисы и жизненный цикл приложения

Одно из частых заблуждений — что push-уведомления обязательно требуют активного foreground-сервиса. На самом деле FCM умеет пробуждать процесс приложения самостоятельно, если в манифесте зарегистрирован нужный BroadcastReceiver. Этого достаточно для короткой обработки данных и записи в локальное хранилище. Однако если требуется выполнить длительную задачу — синхронизацию, скачивание, фоновое обновление — лучше запустить обычный Service, который продолжит работу после того, как FCM отдаст данные.

В Delphi-проектах запуск таких сервисов выполняется через StartService либо через Intent, направленный в собственный Java-класс, обёрнутый в модуль FMX. При этом нужно учитывать ограничения Android 8+ на фоновые сервисы и использовать WorkManager или JobScheduler для отложенных задач. Без этого система может остановить процесс через несколько секунд после того, как приложение свернули, и обработка уведомления просто не успеет выполниться.

Типичные ошибки и инструменты отладки

Самая частая проблема начинающих разработчиков — отсутствие токена у эмулятора, на котором нет Google Play Services. В этом случае любая попытка регистрации возвращает либо пустую строку, либо ошибку, и разработчик тратит часы на проверку манифеста, хотя причина совсем в другом. Вторая по популярности ошибка — неверный package name в google-services.json, из-за чего Firebase отказывается инициализировать клиент ещё на старте.

Для диагностики удобно использовать logcat с фильтрацией по тегам Firebase и GoogleServices. Полезно временно включить подробное логирование в самом приложении и сохранять все ответы сервера в локальный файл. Если push приходит, но приложение его не обрабатывает, проверьте, что BroadcastReceiver зарегистрирован в манифесте и не конфликтует с другими обработчиками. Аккуратное следование этим шагам позволяет получить стабильный канал доставки уведомлений за один рабочий день.