После обновления Flutter push лучше не чинить вслепую переустановкой ключей. Сначала выясните, что именно пропало: сообщение не принято FCM/APNs, приложение его получило, но не показало баннер, либо background handler был удалён tree shaking в release. Эти три поломки выглядят одинаково для пользователя, но проверяются по-разному.
Соберите чистую установку на физическом устройстве и отправляйте тест на один только что полученный FCM token. Эмулятор, старый токен из базы и рассылка на topic добавляют лишние переменные. Зафиксируйте версии Flutter, `firebase_core`, `firebase_messaging`, Android target SDK, iOS deployment target и точный номер сборки.
Матрица из шести тестов сразу сужает поиск
| Сборка и состояние | Что наблюдать | Если не работает |
|---|---|---|
| debug, foreground | FirebaseMessaging.onMessage и payload | инициализация, token, sender/project |
| debug, background | background handler или системный баннер | permission, payload, handler |
| debug, terminated | баннер и открытие через getInitialMessage | нативная конфигурация, force-stop |
| release, foreground | тот же onMessage | release config, shrink/tree shaking |
| release, background | entry point и notification channel | @pragma, channel, permission |
| release, terminated | реальный push после обычного закрытия | APNs entitlement или Android force-stop |
Не путайте обычное закрытие с принудительной остановкой. Firebase указывает: после force-quit из настроек Android приложение надо снова открыть, а на iOS после смахивания из app switcher фоновая доставка возобновляется после ручного запуска. Это ограничение платформы, а не доказательство ошибки сервера.
Инициализация и handler должны пережить release-сборку
Firebase требует top-level background handler, который не является анонимной функцией. Для Flutter 3.3 и новее его нужно пометить `@pragma('vm:entry-point')`, иначе оптимизатор release-сборки может удалить недостижимую из Dart функцию. Если handler использует другие сервисы Firebase, внутри него вызывается `Firebase.initializeApp`.
@pragma('vm:entry-point')
Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
await Firebase.initializeApp(
options: DefaultFirebaseOptions.currentPlatform,
);
// Короткая идемпотентная работа; UI здесь недоступен.
await inbox.saveIfNew(message.messageId, message.data);
}
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await Firebase.initializeApp(
options: DefaultFirebaseOptions.currentPlatform,
);
FirebaseMessaging.onBackgroundMessage(
firebaseMessagingBackgroundHandler,
);
runApp(const App());
}Сделайте handler минимальным: он выполняется вне обычного UI-контекста и не должен зависеть от открытого экрана. По `messageId` или бизнес-идентификатору защищайтесь от повторной обработки. Секреты и полный payload не выводите в production-лог.
Permission проверяют до рассылки, а не после
На iOS, macOS, web и Android 13+ пользователь должен разрешить уведомления. В Android 13 появилось runtime-разрешение `POST_NOTIFICATIONS`; одного объявления в manifest недостаточно для новой установки. После обновления target SDK момент показа системного диалога может измениться, поэтому запросите разрешение в понятном пользовательском сценарии и сохраните фактический `authorizationStatus`.
final settings = await FirebaseMessaging.instance.requestPermission(
alert: true,
badge: true,
sound: true,
);
logger.info('push_permission', {
'status': settings.authorizationStatus.name,
'build': appBuildNumber,
});
if (settings.authorizationStatus == AuthorizationStatus.authorized ||
settings.authorizationStatus == AuthorizationStatus.provisional) {
await syncCurrentToken();
}- Android: проверьте permission в системных настройках и важность notification channel.
- iOS: проверьте Push Notifications capability, APS Environment entitlement и разрешения alert/sound/badge.
- Foreground: видимое уведомление обычно не появляется автоматически; приложение само определяет presentation.
- Data-only payload: ОС может ограничивать фоновую работу сильнее, чем обычный notification payload.
- Не просите permission на старте без объяснения: повторно показать отклонённый диалог часто нельзя.
Свежий токен должен дойти до вашего backend
После обновления приложения, восстановления устройства или смены нативной конфигурации токен может измениться. Firebase даёт `getToken()` и поток `onTokenRefresh`; оба пути должны выполнять один upsert на сервере. На Apple-платформах перед FCM API дождитесь APNs token: актуальная документация Flutter FCM отдельно предупреждает, что он может появиться не сразу.
Future<void> syncCurrentToken() async {
if (Platform.isIOS || Platform.isMacOS) {
final apns = await FirebaseMessaging.instance.getAPNSToken();
if (apns == null) return; // повторить после регистрации APNs
}
final token = await FirebaseMessaging.instance.getToken();
if (token != null) await api.upsertPushToken(token);
}
FirebaseMessaging.instance.onTokenRefresh.listen((token) async {
await api.upsertPushToken(token);
});На backend храните токен с user, device, platform, app build и временем последнего подтверждения. Ошибки провайдера о незарегистрированном токене должны деактивировать запись. Не показывайте токен в тикете целиком: достаточно последних символов и хеша для сопоставления.
Foreground без баннера может быть правильным поведением
Firebase сообщает, что notification message, полученное в foreground, по умолчанию не показывает видимый баннер. На Android нужен канал с подходящей важностью и локальный показ, на iOS — foreground presentation options или собственный UI. Поэтому `onMessage` в логе при отсутствии баннера означает, что транспорт работает.
| Есть в логе | Баннера нет | Следующий шаг |
|---|---|---|
| onMessage | только foreground | настроить presentation/local notification |
| background handler | data-only payload | проверить бизнес-UI и ограничения фоновой работы |
| успех FCM send | ни в одном состоянии | проверить token, project и нативную регистрацию |
| ничего в release | debug работает | проверить @pragma и release-конфигурацию |
Нативные файлы сверяют с текущим приложением
Проверьте, что `google-services.json` относится к фактическому Android applicationId, а `GoogleService-Info.plist` — к iOS bundle identifier текущего flavor. В Xcode должны быть capability Push Notifications и правильный signing entitlement. APNs device token уникален для приложения и устройства; Apple рекомендует получать актуальный токен при запуске и отправлять его provider server, а не считать локально закешированное значение вечным.
- Удалить приложение, установить текущую release-сборку и записать permission status.
- Получить APNs token на iOS и FCM token; сравнить project/app id без публикации секретов.
- Отправить notification payload через официальный тестовый инструмент на один токен.
- Повторить foreground, background и terminated без force-stop.
- Отправить data-only payload и подтвердить вход background handler по безопасной метрике.
- Обновить приложение поверх предыдущей версии и снова сравнить token/permission/channel.
- Проверить открытие по нажатию через `onMessageOpenedApp` и `getInitialMessage`.
Исправление считается доказанным, когда один и тот же сценарий проходит в debug и release на физическом Android 13+ и поддерживаемой iOS, а backend видит актуальный token refresh. Такой отчёт намного полезнее фразы «push снова работают»: он показывает, какой слой был сломан и какое обновление не должно повторить поломку.