Flutter Push Notifications: The Complete Setup Guide (2026)

dependencies:
  flutter:
    sdk: flutter
  firebase_core: ^3.0.0
  firebase_messaging: ^15.0.0

flutter pub get

import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_messaging/firebase_messaging.dart';

// Top-level background handler (must be outside any class)
@pragma('vm:entry-point')
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  await Firebase.initializeApp();
  print('Background message: ${message.messageId}');
  // Handle your background notification here
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  
  // Register background handler
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
  
  runApp(const MyApp());
}

buildscript {
  dependencies {
    // Add this line
    classpath 'com.google.gms:google-services:4.4.0'
  }
}

apply plugin: 'com.google.gms.google-services'

<!-- android/app/src/main/AndroidManifest.xml -->
<manifest ...>
  <application ...>
    <!-- Required for heads-up notifications on Android 13+ -->
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    
    <!-- Keep this for FCM to work properly -->
    <service
      android:name="com.google.firebase.messaging.FirebaseMessagingService"
      android:exported="false">
      <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
      </intent-filter>
    </service>
  </application>
</manifest>

class _NotificationSetup extends State<NotificationSetup> {
  @override
  void initState() {
    super.initState();
    _setupNotifications();
  }

  Future<void> _setupNotifications() async {
    final messaging = FirebaseMessaging.instance;
    
    // Request permission (iOS requires this, Android 13+ requires this)
    final settings = await messaging.requestPermission(
      alert: true,
      badge: true,
      sound: true,
    );
    
    if (settings.authorizationStatus == AuthorizationStatus.authorized) {
      print('User granted permission');
      
      // Get the FCM token
      final token = await messaging.getToken();
      print('FCM Token: $token');
      
      // Send token to your backend or PushPilot
      await _sendTokenToServer(token!);
    }
  }
}

void _listenForMessages() {
  // Foreground messages (app is open)
  FirebaseMessaging.onMessage.listen((RemoteMessage message) {
    print('Foreground message: ${message.notification?.title}');
    
    // Show a local notification or update UI
    if (message.notification != null) {
      _showLocalNotification(message.notification!);
    }
  });

  // When user taps a notification that opened the app
  FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
    print('User tapped notification: ${message.data}');
    _handleNotificationTap(message.data);
  });
}

// Check if app was launched from a notification (terminated state)
Future<void> _checkInitialMessage() async {
  final message = await FirebaseMessaging.instance.getInitialMessage();
  if (message != null) {
    _handleNotificationTap(message.data);
  }
}

FirebaseMessaging.instance.onTokenRefresh.listen((newToken) {
  // Update the token in your backend
  _sendTokenToServer(newToken);
});

// Subscribe a device to a topic
await FirebaseMessaging.instance.subscribeToTopic('daily_reminders');
await FirebaseMessaging.instance.subscribeToTopic('premium_users');

// Unsubscribe from a topic
await FirebaseMessaging.instance.unsubscribeFromTopic('daily_reminders');

// Example: subscribe on login, unsubscribe on logout
Future<void> onUserLogin(String userId, bool isPremium) async {
  await FirebaseMessaging.instance.subscribeToTopic('all_users');
  if (isPremium) {
    await FirebaseMessaging.instance.subscribeToTopic('premium_users');
  }
}