Notifications
Displaying & handling notifications from FCM.
Notifications are an important tool used on the majority of Android & iOS applications, used to improve user experience, used to engage users with your application and much more. The Cloud Messaging module provides basic support for displaying and handling notifications.
Looking for an advanced local notifications library which integrates with FCM? Check out Notifee!
Displaying a Notification
The Firebase Cloud Messaging SDKs for Android and iOS allow for notifications to be displayed on devices when the application
is either quit or in the background. The Firebase Console, Firebase Admin SDKs and REST API all allow a notification
property to be attached to a message.
If an incoming message with this property exists, and the app is not currently visible (quit or in the background), a notification is displayed on the device. However, if the application is in the foreground, an event will be delivered containing the notification data and no visible notification will be displayed. See the Usage documentation to learn more about handling events.
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 images.
- Target applications which have been added to your project.
- Schedule notifications to display at a later date.
- Send recurring notifications.
- Assign conversion events for your analytical tracking.
- A/B test user interaction (called "experiments").
- Test notifications on your development devices.
The Firebase Console automatically sends a message to your devices containing a notification
property which is handled
by the React Native Firebase Cloud Messaging module. See Handling Interaction to learn about how
to support user interaction.
Via Admin SDKs
The various Firebase Admin SDKs allow you to send messages to your users. If these messages also contain notification options, the React Native Firebase Cloud Messaging module will automatically display these notifications.
For example, when using the firebase-admin
package in a Node.js environment
to send messages from a server, a notification
property can be added to the message payload:
await admin.messaging().sendMulticast({
tokens: [
/* ... */
], // ['token_1', 'token_2', ...]
notification: {
title: 'Basic Notification',
body: 'This is a basic notification sent from the server!',
imageUrl: 'https://my-cdn.com/app-logo.png',
},
});
The Cloud Messaging module will intercept these messages and if the notification
property is available, it will display
a notification on the device (if the app is not in the foreground). Messages sent with both a notification
and data
property
will display a notification and also trigger the onMessage
handlers (see Usage).
The different Admin SDKs available have similar implementation details on how to add a custom notification
property to
the FCM payload, however the Cloud Messaging module will handle all requests. To learn more, view the
Firebase Admin SDK documentation for your chosen admin SDK. For those using the
HTTP implementation, view the REST Cloud Messaging
reference.
Via REST
If you are unable to use a Firebase Admin SDK, Firebase also provides support for sending messages to devices via a POST request:
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"data":{},
"notification":{
"body":"This is an FCM notification message!",
"title":"FCM Message"
}
}
}
To learn more about the REST API, view the Firebase documentation, and select the "REST" tab under the code examples.
Handling Interaction
When a user interacts with your notification by pressing on it, the default behavior is to open the application (since notifications via FCM only display when the application is in the background, the application will always open).
In many cases, it is useful to detect whether the application was opened by pressing on a notification (so you could open a specific screen for example). The API provides two APIs for handling interaction:
getInitialNotification
: When the application is opened from a quit state.onNotificationOpenedApp
: When the application is running, but in the background.
To handle both scenarios, the code can be executed during setup. For example, using React Navigation we can set an initial route when the app is opened from a quit state, and push to a new screen when the app is in a background state:
import React, { useState, useEffect } from 'react';
import messaging from '@react-native-firebase/messaging';
import { NavigationContainer, useNavigation } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';
const Stack = createStackNavigator();
function App() {
const navigation = useNavigation();
const [loading, setLoading] = useState(true);
const [initialRoute, setInitialRoute] = useState('Home');
useEffect(() => {
// Assume a message-notification contains a "type" property in the data payload of the screen to open
messaging().onNotificationOpenedApp(remoteMessage => {
console.log(
'Notification caused app to open from background state:',
remoteMessage.notification,
);
navigation.navigate(remoteMessage.data.type);
});
// Check whether an initial notification is available
messaging()
.getInitialNotification()
.then(remoteMessage => {
if (remoteMessage) {
console.log(
'Notification caused app to open from quit state:',
remoteMessage.notification,
);
setInitialRoute(remoteMessage.data.type); // e.g. "Settings"
}
setLoading(false);
});
}, []);
if (loading) {
return null;
}
return (
<NavigationContainer>
<Stack.Navigator initialRouteName={initialRoute}>
<Stack.Screen name="Home" component={HomeScreen} />
<Stack.Screen name="Settings" component={SettingsScreen} />
</Stack.Navigator>
</NavigationContainer>
);
}
The call to getInitialNotification
should happen within a React lifecycle method after mounting (e.g. componentDidMount
or useEffect
).
If it's called too soon (e.g. within a class constructor or global scope), the notification data may not be available.
Quick Tip: On Android
you can test receiving remote notifications on the emulator but on iOS
you will need to use a real device as the iOS simulator does not support receiving remote notifications.
Notifee - Advanced Notifications
FCM provides support for displaying basic notifications to users with minimal integration required. If however you require more advanced notifications you need to integrate with a 3rd party local notifications package, such as Notifee.
Android Features
- Advanced channel and group management.
- Custom appearance with HTML text styling, custom icons, badge support, colors and more.
- Behavior management such as custom sounds, vibration patterns, device notification light management and more.
- Displaying on-going Foreground Service Notifications for dealing with long-running background tasks.
- Advanced interaction handling with action buttons, quick reply features and more.
- Support for built in styling; Big Picture Style, Big Text Style, Inbox Style & Messaging Style notifications.
- Adding Progress Indicators & Timers to your notification.
iOS Features
- Advanced Permission management.
- Behavior management such as custom sounds and critical notifications.
- Creating actions & categories.
To learn more about integrating FCM with Notifee, view the integration documentation.