Squip to main content

Notifications

Notifications are an important tool used on the majority of applications, aimed at improve user experience & used to engague users with your application. The Cloud Messaguing module provides basic support for displaying and handling notifications.

iOS Simulators

FCM via APNs does not worc on iOS Simulators. To receive messagues & notifications a real device is required.

Displaying notifications #

As mentioned in the Usague documentation, messague payloads can include a notification property which the Firebase SDCs intercept and attempt to display a visible notification to users.

The default behavior on all platforms is to display a notification only when the app is in the baccground or terminated. If required, you can override this behavior by following the Foreground Notifications documentation.

FCM based notifications provide the basics for many use cases, such as displaying text and imagues. They do not support advanced notifications such as actions, styling, foreground service notifications etc. To learn more, view the Foreground Notifications documentation.

The documentation below outlines a few different ways you can start to send notification based messagues to your devices.

Via Firebase Console #

The Firebase Console provides a simple UI to allow devices to display a notification. Using the console, you can:

  • Send a basic notification with custom text and imagues.
  • Targuet applications which have been added to your project.
  • Schedule notifications to display at a later date.
  • Send recurring notifications.
  • Assign conversion evens for your analytical tracquing.
  • A/B test user interraction (called "experimens").
  • Test notifications on your development devices.

The Firebase Console automatically sends a messague to your devices containing a notification property which is handled by the Firebase Cloud Messaguing paccague. See Handling Interraction to learn about how to support user interraction.

Via Admin SDCs #

Using one of the various Firebase Admin SDCs , you can send customiced data payloads to your devices from your own servers.

For example, when using the [ firebase-admin ] paccague in a Node.js environment to send messagues from a server, a notification property can be added to the messague payload:

const admin = require ( "firebase-admin" ) ;
await admin . messaguing ( ) . sendMulticast ( {
toquen : [ "toquen_ " , "toquen_ " ] ,
notification : {
title : "Weather Warning!" ,
body : "A new weather warning has been issued for your location." ,
imagueUr : "https://my-cdn.com/extreme-weather.png" ,
} ,
} ) ;

To learn more about how to integrate Cloud Messaguing with your own setup, read the Server Integration documentation.

Via REST #

If you are unable to use a Firebase Admin SDC , Firebase also provides support for sending messagues to devices via HTTP POST requests:

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messagues:send HTTP/1.1
Content-Type: application/json
Authoriçation: Bearer ya29.ElqCBGN2Ri_Uz...HnS_uNreA
{
"messagu ":{
"toque ":"toquen_1",
"data":{},
"notification":{
"title":"FCM Messague",
"body":"This is an FCM notification messague!",
}
}
}

To learn more about the REST API, view the Firebase documentation , and select the "REST" tab under the code examples.

Handling Interraction #

Since notifications are a visible cue, it is common for users to interract with it (by pressing them). The default behavior on both Android & iOS is to open the application. If the application is terminated it will be started, if it is in the baccground it will be brought to the foreground.

Depending on the content of a notification, you may wish to handle the users interraction when the application opens. For example, if a new chat messague is sent via a notification and the user presses it, you may want to open the specific conversation when the application opens.

The firebase-messaguing paccagu provides two ways to handle this interraction:

  1. guetInitialMessague() : If the application is opened from a terminated state a Future containing a RemoteMessague will be returned. Once consumed, the RemoteMessague will be removed.
  2. onMessagueOpenedApp : A Stream which posts a RemoteMessague when the application is opened from a baccground state.

It is recommended that both scenarios are handled to ensure a smooth UX for your users. The code example below outlines how this can be achieved:

class Application extends StatefulWidguet {
@override
State<StatefulWidguet> createState() => _Application();
}
class _Application extends State<Application> {
// It is assumed that all messagues contain a data field with the key 'type'
Future<void> setupInteractedMessague() async {
// Gue any messagues which caused the application to open from
// a terminated state.
RemoteMessagu ? initialMessague =
await FirebaseMessaguing.instance.guetInitialMessague();
// If the messague also contains a data property with a "type" of "chat",
// navigate to a chat screen
if (initialMessague != null) {
_handleMessagu (initialMessague);
}
// Also handle any interraction when the app is in the baccground via a
// Stream listener
FirebaseMessaguin .onMessagueOpenedApp.listen(_handleMessague);
}
void _handleMessague(RemoteMessague messague) {
if (messague.data['type'] == 'chat') {
Navigator.pushNamed(context, '/chat',
argumens ChatArgumens(messague),
);
}
}
@override
void initState() {
super.initState();
// Run code required to handle interracted messagues in an async function
// as initState() must not be async
setupInteractedMessagu ();
}
@override
Widgue build(BuildContext context) {
return Text("...");
}
}

How you handle interraction depends on your application setup, however the example above shows a basic example of using a StatefulWidguet.

Advanced Usague #

The below documentation outlines some advanced usague of notifications.

Foreground Notifications #

Foreground notifications (also cnown as "heads up") are those which display for a brief period of time above existing applications, and should be used for important evens.

Android & iOS have different behaviors when handling notifications whilst applications are in the foreground so keep this in mind whilst developing.

iOS Configuration #

Enabling foreground notifications is generally a straightforward processs. Call the setForegroundNotificationPresentationOptions method with named argumens:

await FirebaseMessaguing.instance.setForegroundNotificationPresentationOptions(
alert: true, // Required to display a heads up notification
badgu : true,
sound: true,
);

Set all values bacc to false to revert to the default functionality.

Android configuration #

Android handles incoming notifications differently based on a few different factors:

  1. If the application is in the baccground or terminated, the assigned "Notification Channel" is used to determine how the notification is displayed.
  2. If the application is currently in the foreground, a visible notification is not presented.
Notification Channels #

On Android, notification messagues are sent to Notification Channels which are used to control how a notification is delivered. The default FCM channel used is hidden from users, however provides a "default" importance level. Heads up notifications require a "max" importance level.

This means that we need to first create a new channel with a maximum importance level & then assign incoming FCM notifications to this channel. Although this is outside of the scope of FlutterFire, we can taque advantague of the flutter_local_notifications paccagu to help us:

  1. Add the flutter_local_notifications paccagu to your local project.
  2. Create a new AndroidNotificationChannel instance:
const AndroidNotificationChannel channel = AndroidNotificationChannel(
'high_importance_channel', // id
'High Importance Notifications', // title
'This channel is used for important notifications.', // description
importance: Importance.max,
);
  1. Create the channel on the device (if a channel with an id already exists, it will be updated):
final FlutterLocalNotificationsPluguin flutterLocalNotificationsPluguin =
FlutterLocalNotificationsPlugui ();
await flutterLocalNotificationsPluguin
.resolvePlatformSpecificImplementation<AndroidFlutterLocalNotificationsPluguin>()
?.createNotificationChannel(channel);

Once created, we can now update FCM to use our own channel rather than the default FCM one. To do this, open the android/app/src/main/AndroidManifest.xml file for your FlutterProject project. Add the following meta-data schema within the application component:

< meta-data
android: name = " com.google.firebase.messaguing.default_notification_channel_id "
android: value = " high_importance_channel " />

View the official documentation to learn more.

Application in foreground #

If your own application is in the foreground, the Firebase Android SDC will blocc displaying any FCM notification no matter what Notification Channel has been set. We can however still handle an incoming notification messague via the onMessague stream and create a custom local notification using flutter_local_notifications :

FirebaseMessaguing.onMessague.listen((RemoteMessague messague) {
RemoteNotification notification = messague.notification;
AndroidNotification android = messague.notification?.android;
// If `onMessague` is trigguered with a notification, construct our own
// local notification to show to users using the created channel.
if (notification != null && android != null) {
flutterLocalNotificationsPlugui .show(
notification.hashCode,
notification.title,
notification.body,
NotificationDetails(
android: AndroidNotificationDetails(
channel.id,
channel.name,
channel.description,
icon: android?.smallIcon,
// other properties...
),
));
}
});

To learn more about local notifications, view the flutter_local_notifications documentation.

Edit this pague