После обновления Flutter push лучше не чинить вслепую переустановкой ключей. Сначала выясните, что именно пропало: сообщение не принято FCM/APNs, приложение его получило, но не показало баннер, либо background handler был удалён tree shaking в release. Эти три поломки выглядят одинаково для пользователя, но проверяются по-разному.

Соберите чистую установку на физическом устройстве и отправляйте тест на один только что полученный FCM token. Эмулятор, старый токен из базы и рассылка на topic добавляют лишние переменные. Зафиксируйте версии Flutter, `firebase_core`, `firebase_messaging`, Android target SDK, iOS deployment target и точный номер сборки.

Матрица из шести тестов сразу сужает поиск

Сборка и состояниеЧто наблюдатьЕсли не работает
debug, foregroundFirebaseMessaging.onMessage и payloadинициализация, token, sender/project
debug, backgroundbackground handler или системный баннерpermission, payload, handler
debug, terminatedбаннер и открытие через getInitialMessageнативная конфигурация, force-stop
release, foregroundтот же onMessagerelease config, shrink/tree shaking
release, backgroundentry 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 handlerdata-only payloadпроверить бизнес-UI и ограничения фоновой работы
успех FCM sendни в одном состояниипроверить token, project и нативную регистрацию
ничего в releasedebug работаетпроверить @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, а не считать локально закешированное значение вечным.

  1. Удалить приложение, установить текущую release-сборку и записать permission status.
  2. Получить APNs token на iOS и FCM token; сравнить project/app id без публикации секретов.
  3. Отправить notification payload через официальный тестовый инструмент на один токен.
  4. Повторить foreground, background и terminated без force-stop.
  5. Отправить data-only payload и подтвердить вход background handler по безопасной метрике.
  6. Обновить приложение поверх предыдущей версии и снова сравнить token/permission/channel.
  7. Проверить открытие по нажатию через `onMessageOpenedApp` и `getInitialMessage`.

Исправление считается доказанным, когда один и тот же сценарий проходит в debug и release на физическом Android 13+ и поддерживаемой iOS, а backend видит актуальный token refresh. Такой отчёт намного полезнее фразы «push снова работают»: он показывает, какой слой был сломан и какое обновление не должно повторить поломку.

Проверенные источники