Push-уведомления в Delphi через Firebase Cloud Messaging
Push-уведомление позволяет приложению сообщить пользователю о важном событии без активного открытия интерфейса. В Delphi-сценарии это могут быть подтверждение заказа, новый комментарий, смена статуса задачи или сигнал тревоги. Firebase Cloud Messaging берёт на себя доставку через инфраструктуру Google и отделяет клиентскую логику от серверной отправки.
На стороне клиента FireMonkey-приложение получает токен устройства и передаёт его серверному API. Сервер сохраняет токен, связывает его с учётной записью или ресурсом пользователя, а затем отправляет сообщение через FCM HTTP v1. Секретный ключ сервисного аккаунта при этом остаётся только на сервере и не попадает в мобильный пакет.
Для небольшого проекта роль API может выполнять PHP-сервис с PostgreSQL или MySQL. Он хранит токены, историю рассылок и результаты доставки, обращается к Firebase по OAuth 2.0 и возвращает клиенту актуальное состояние подписки. Серверная часть не зависит от того, открыто ли приложение в момент события.
Перед реализацией важно развести регистрацию приложения, получение токена, отправку сообщения и показ уведомления. Каждый этап имеет собственные подтверждения и ошибки: клиент сообщает о токене, API фиксирует подписку, Firebase возвращает результат доставки, а система уведомлений учитывает разрешения пользователя.
Подготовка Firebase-проекта
Сначала в Firebase Console создаётся проект, а в нём — приложения Android и iOS. Идентификатор Android должен точно совпадать с именем пакета, а идентификатор iOS — с bundle ID. Для каждой платформы загружаются собственные google-services.json и GoogleService-Info.plist; их добавляют в сборку через предусмотренный в Delphi механизм ресурсов.
Отдельный сервисный аккаунт с правом отправки сообщений создаётся для серверной части. JSON-файл ключа хранится в переменных окружения или секрет-хранилище, а пользователю Firebase выдаются только необходимые роли. Файлы конфигурации клиента не содержат этого ключа, поэтому даже случайное извлечение мобильного пакета не раскрывает серверные права.
Получение токена устройства
Токен получается через Firebase Messaging SDK, подключённый к нативной части FireMonkey-проекта совместимым компонентом или мостом. На Android SDK возвращает регистрационный токен FCM, а на iOS сначала использует токен устройства APNs и регистрирует его в Firebase. Слушатель нового токена должен сразу отправлять обновление на сервер.
Токен — временный идентификатор, поэтому сервер хранит дату проверки, платформу, пользователя и статус активности. При переустановке приложения, сбросе данных или переносе на другой смартфон старое значение перестаёт быть надёжным. API подтверждает регистрацию после проверки формата и источника, а удаляет или блокирует токен, который Firebase признал недействительным.
Отправка через FCM HTTP v1
Серверная часть получает краткоживущий OAuth 2.0 bearer token для сервисного аккаунта и вызывает ресурс projects/{project_id}/messages:send. В объекте message указываются токен получателя, поля notification, пользовательские ключи data, а при необходимости — настройки Android или APNs. Значения data передаются как строки, поэтому идентификаторы и флаги заранее преобразуются в явный формат.
Выбор состава сообщения определяет момент показа. Обычное уведомление удобно для коротких новостей, а сообщение с данными позволяет приложению самостоятельно решить, создавать ли локальное уведомление.
| Формат FCM | Что находится в сообщении | Поведение клиента |
|---|---|---|
| Только данные | Только ключи data |
Приложение обрабатывает их в фоне и само создаёт уведомление |
| Уведомление | title, body и данные |
В фоне система показывает уведомление, в переднем плане срабатывает обработчик |
| Данные и параметры платформы | Данные, notification, android или apns |
Можно задать канал, звук, приоритет и поведение открытия |
Ответ сервиса содержит идентификатор сообщения или причину отказа. Код 404 обычно означает неизвестный или недействительный токен, 401 и 403 — проблемы авторизации и прав, 429 — превышение квоты, а 5xx — временный сбой Google. Сервер разделяет эти категории: повторяет сетевую ошибку, обновляет подписку или отправляет сообщение в очередь.
Обработка сообщений в FireMonkey
В обработчике JSON сначала разбирается через System.JSON, затем извлекаются title, body и собственные ключи. Событие получения сообщения связывается с жизненным циклом приложения, а маршрут из data используется для открытия нужного экрана. Значения проверяются до преобразования в число, дату или объект, поскольку FCM доставляет пользовательские данные строками.
Работа в фоне требует отдельного канала доставки, который поддерживает выбранный компонент Firebase. Android-сервис принимает сообщение с данными высокого приоритета, а на iOS доступность фонового запуска зависит от режима APNs и политики системы. Обработчик интерфейса выполняется в основном потоке FMX, чтобы не нарушить жизненный цикл форм и компонентов.
Для Windows, macOS и Linux серверный слой можно сохранить, но клиентский адаптер зависит от доступной интеграции FCM. Мобильный токен нельзя считать действительным для настольной ОС, поэтому каждой платформе соответствует своя подписка или иной системный механизм уведомлений. Единый API отправки сохраняется, а платформенный код приёма разделяется.
Права и настройки платформ
На Android 13 и новее требуется явное разрешение POST_NOTIFICATIONS, которое запрашивается в понятный для пользователя момент. Канал уведомлений создаётся до первой отправки и задаёт название, важность и звук; в FCM указывается соответствующий channel_id. Если канал создан с низкой важностью, последующие настройки приложения не всегда изменяют поведение, выбранное пользователем в системе.
На iOS проект включает capability Push Notifications и APNs environment, согласованный с режимом сборки. Firebase использует APNs под капотом, однако уведомление появляется только после разрешения пользователя на alert, badge и sound. Разрешение запрашивают после объяснения назначения, а тестирование ведут на физическом устройстве, поскольку симулятор не воспроизводит все условия APNs.
Для проекта, охватывающего мобильные и настольные версии, разработка клиентских приложений может объединить общий API, разные пользовательские интерфейсы и единый цикл проверки. Серверная схема FCM при этом остаётся неизменной: меняются только получение токена, разрешения и способ показа уведомления на целевой платформе.
Надёжность доставки и мониторинг
Надёжность доставки строится вокруг актуального состояния токенов и повторяемых попыток. При ошибке 404 запись помечается неактивной, при 429 сервер соблюдает интервал повтора, а при временном 5xx использует очередь с задержкой. Уникальный идентификатор события и журнал попыток помогают избежать дубликатов после перезапуска процесса обработки.
Наблюдаемость строится по идентификатору сообщения, HTTP-коду, времени ответа и журналу ошибок. Подход к контролю PHP-сервиса показан в материале о PHP-мониторинге: регулярные проверки и оповещения дополняют историю рассылок. Персональные данные и полные токены в журналы не записываются.
Ошибки доставки различают по владельцу: неверная авторизация требует исправления сервера, истёкший токен — обновления подписки, а переполненная квота — изменения настроек рассылки. Повторная отправка одного сообщения допустима не для всех ошибок, поэтому политику очереди связывают с типом уведомления и допустимой задержкой.
Проверка и типичные ошибки
Проверка выполняется по контрольному сценарию: при открытом интерфейсе, в фоне, при закрытом приложении, на Android и iOS, на реальном устройстве и после переустановки. Во время теста меняют содержимое data, проверяют переход по ссылке, обновление токена и отказ от разрешения. Отдельно наблюдают, не показывает ли приложение одно уведомление дважды — системное и созданное локально.
Наиболее частые сбои связаны с несовпадением имени пакета Android или идентификатора bundle iOS, отсутствием файлов конфигурации Firebase, неверным channel_id и неподписанным APNs-ключом. В рабочей среде используют отдельные проекты Firebase для тестов и продукции, секреты хранят вне репозитория, а сроки действия ключей и сертификатов контролируют заранее. Такой порядок делает push-уведомления воспроизводимыми и позволяет быстро отличить проблему клиента от ошибки сервера.