Sending Push Notifications to Flutter Apps with FCM

📅

loading..🐩🐩🐩🐩

Before We Begin 🔗

This guide was written for Flutter 3.24.

It assumes your Flutter app is already connected to a Firebase project. If you need to create one, see Register a Flutter app with Firebase.

What Is FCM? 🔗

FCM architecture overview — source: https://firebase.google.com/docs/cloud-messaging/fcm-architecture

Firebase Cloud Messaging (FCM) is a cross-platform messaging service that reliably delivers messages at no cost. An FCM implementation has two main parts.

A trusted environment, such as Cloud Functions for Firebase or an app server, that creates, targets, and sends messages.
An Apple, Android, or web (JavaScript) client that receives messages through its platform's transport service.

The first part is typically your backend. The second is your Flutter app. This guide focuses on the Flutter side: obtaining an FCM token and receiving push notifications.

1. Set Up iOS 🔗

You need an Apple Developer account. If you don't have one, join Apple Developer↗ or skip this section and continue with Android.

1.1. Create an APNs Authentication Key 🔗

Enter a name and select APNs.
Click Configure and choose the options you need.
Click Continue, then Register to create the key.

🖐️
Download the key now and store it somewhere safe.

The new key should appear as shown below.

1.2. Register an Identifier 🔗

Select App IDs, choose App on the next screen, and click Continue.
Enter a description and bundle ID. Scroll down, select Push Notifications, and click Continue, then Register.
The bundle ID is the PRODUCT_BUNDLE_IDENTIFIER value in /ios/Runner.xcodeproj/project.pbxproj, for example com.example.promleeblog.

1.3. Add Xcode Capabilities 🔗

In VS Code, right-click the /ios folder and choose Open in Xcode.

Go to Runner > Runner > Signing & Capabilities, click + Capability, then search for and add Push Notifications.

In the Signing & Capabilities tab, also select the Background Modes options shown below.

1.4. Configure the Firebase Console 🔗

Cloud Messaging

tab as shown below.

Upload the key created in section 1.1. Find the Key ID on the key's details page and the Team ID on the Apple Developer portal — Account↗ page.

Where to find the Team ID

That completes the iOS configuration.

1.5. Configure Permission in the Podfile 🔗

Add the permission below to /ios/Podfile. If the configuration is already there, make sure PERMISSION_NOTIFICATIONS is uncommented.

Podfile code

/ios/Podfile

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      # You can remove unused permissions here
      # for more information: https://github.com/BaseflowIT/flutter-permission-handler/blob/master/permission_handler/ios/Classes/PermissionHandlerEnums.h
      # e.g. when you don't need camera permission, just add 'PERMISSION_CAMERA=0'
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',
 
        ## dart: PermissionGroup.calendar
        # 'PERMISSION_EVENTS=1',
 
        ## dart: PermissionGroup.calendarFullAccess
        # 'PERMISSION_EVENTS_FULL_ACCESS=1',
 
        ## dart: PermissionGroup.reminders
        # 'PERMISSION_REMINDERS=1',
 
        ## dart: PermissionGroup.contacts
        # 'PERMISSION_CONTACTS=1',
 
        ## dart: PermissionGroup.camera
        # 'PERMISSION_CAMERA=1',
 
        ## dart: PermissionGroup.microphone
        # 'PERMISSION_MICROPHONE=1',
 
        ## dart: PermissionGroup.speech
        # 'PERMISSION_SPEECH_RECOGNIZER=1',
 
        ## dart: PermissionGroup.photos
        # 'PERMISSION_PHOTOS=1',
 
        ## The 'PERMISSION_LOCATION' macro enables the `locationWhenInUse` and `locationAlways` permission. If
        ## the application only requires `locationWhenInUse`, only specify the `PERMISSION_LOCATION_WHENINUSE`
        ## macro.
        ##
        ## dart: [PermissionGroup.location, PermissionGroup.locationAlways, PermissionGroup.locationWhenInUse]
        # 'PERMISSION_LOCATION=1',
        # 'PERMISSION_LOCATION_WHENINUSE=0',
 
        ## dart: PermissionGroup.notification
        'PERMISSION_NOTIFICATIONS=1',
 
        ## dart: PermissionGroup.mediaLibrary
        # 'PERMISSION_MEDIA_LIBRARY=1',
 
        ## dart: PermissionGroup.sensors
        # 'PERMISSION_SENSORS=1',
 
        ## dart: PermissionGroup.bluetooth
        # 'PERMISSION_BLUETOOTH=1',
 
        ## dart: PermissionGroup.appTrackingTransparency
        # 'PERMISSION_APP_TRACKING_TRANSPARENCY=1',
 
        ## dart: PermissionGroup.criticalAlerts
        # 'PERMISSION_CRITICAL_ALERTS=1',
 
        ## dart: PermissionGroup.criticalAlerts
        # 'PERMISSION_ASSISTANT=1',
      ]
 
    end
  end
end

2. Set Up Android 🔗

On Android 13 (API level 33) and later, configure the notification permission as shown below.

/android/app/src/main/AndroidManifest.xml

<manifest ...>
	<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
	<application ...>
			...
	</application>
</manifest>

3. Write the Flutter Code to Receive Push Notifications 🔗

3.1. Install firebase_messaging 🔗

flutter pub add firebase_messaging

3.2. Request Notification Permission 🔗

Add this code where you want to ask the user for permission to receive notifications.

import 'package:firebase_messaging/firebase_messaging.dart';
 
// 적절한 위치에 선언
FirebaseMessaging messaging = FirebaseMessaging.instance;
NotificationSettings settings = await messaging.requestPermission(
  alert: true,
  announcement: false,
  badge: true,
  carPlay: false,
  criticalAlert: false,
  provisional: false,
  sound: true,
);
print('User granted permission: ${settings.authorizationStatus}');

3.3. Handle Notifications in the Background 🔗

Add the following to the top-level main.dart file.

Keep these requirements in mind when writing a background message handler.

It must be a named function.
It must be a top-level function, such as a standalone function instead of a method on a class that requires initialization.
With Flutter 3.3.0 and later, annotate it with @pragma('vm:entry-point') immediately above the declaration. Otherwise, tree shaking may remove it in release mode.

/lib/main.dart

import 'package:firebase_messaging/firebase_messaging.dart';
 
@pragma('vm:entry-point')
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  await Firebase.initializeApp();
}
 
void main() {
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
  runApp(MyApp());
}

3.4. Handle Notifications in the Foreground 🔗

Add the following listener to the top-level file.

/lib/main.dart

import 'package:firebase_messaging/firebase_messaging.dart';
 
void main(){
	// ...
	FirebaseMessaging.onMessage.listen((RemoteMessage message) {
		print('Got a message whilst in the foreground!');
		print('Message data: ${message.data}');
 
		if (message.notification != null) {
			print('Message also contained a notification: ${message.notification}');
		}
	});
  runApp(MyApp());
}

4. Get an FCM Token 🔗

4.1. What Is an FCM Token? 🔗

An FCM token is a unique identifier a Flutter app uses to communicate with FCM. With a token, the app can receive push notifications.

4.2. Retrieve the Token 🔗

import 'package:firebase_messaging/firebase_messaging.dart';
 
// 적절한 위치에 선언
final req = await FirebaseMessaging.instance.requestPermission(
	alert: true,
	badge: true,
	sound: true,
);
final fcmToken = await FirebaseMessaging.instance.getToken();
if (req.authorizationStatus == AuthorizationStatus.authorized && fcmToken != null) {
	print('FCM Token: $fcmToken');
} else {
	print('FCM Token: null');
}

5. Send a Test Message 🔗

Install the app on the device first.
Sign in to Firebase Console — Cloud Messaging↗ and choose your project.
Click Create your first campaign, select Firebase 알림 메시지 (Firebase Notification messages), and click Create.

Open the notification composer, enter a title and message, and click Send test message to send it to the FCM token you obtained earlier.

Troubleshooting 🔗

Failed to Get an FCM Token on iOS 🔗

apns token has not been set yet. please ensure the apns token is available by calling getapnstoken()

Even with the basic configuration in place, this error can appear when Flutter does not obtain the APNs token automatically. In that case, retrieve the APNs token explicitly.

/lib/main.dart

import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:flutter/material.dart';
 
void main() async {
	WidgetsFlutterBinding.ensureInitialized();
	FirebaseMessaging messaging = FirebaseMessaging.instance;
	await messaging.requestPermission(
		alert: true,
		announcement: false,
		badge: true,
		carPlay: false,
		criticalAlert: false,
		provisional: false,
		sound: true,
	);
	messaging.getAPNSToken(); // 이 코드 추가
	await messaging.getToken();
	runApp(MyApp());
}

You may see this error after installing and running the app on a physical iOS device. On iOS, the APNs token must be available before you request an FCM token. Update your code as shown above to retrieve the APNs token first, then request the FCM token.

Conclusion 🔗

Firebase Cloud Messaging makes sending push notifications straightforward. Opening a specific page or performing an action when the user taps a notification takes additional work. We'll cover that in the next post.

Further Considerations 🔗

Send push notifications with the HTTP v1 API.
Open a specific page when the user taps a push notification.
Perform a specific action when the user taps a push notification.

References 🔗

Using Firebase Cloud Messaging with Flutter↗

Sending Push Notifications to Flutter Apps with FCM | PromleeBlog