Capacitor Firebase Cloud Messaging Plugin

Unofficial Capacitor plugin for Firebase Cloud Messaging.[^1]

Use Cases

The Firebase Cloud Messaging plugin is typically used to engage and re-engage users with push notifications, for example:

• Push notifications: Notify users about new content, messages, or offers, even when the app is not in the foreground.
• Topic-based messaging: Let users subscribe to topics such as news categories and send a message to all subscribers of a topic at once.
• Device targeting: Retrieve the FCM token of a device to send push messages to specific users or devices.
• Background data sync: Receive data push notifications in the background to keep the content of your app up to date.
• Notification management: List, remove, or clear the notifications that are visible on the notifications screen.

Compatibility

Guides

• The Push Notifications Guide for Capacitor
• How to Use Firebase in a Capacitor App: From push notifications to analytics and crash reporting — every Firebase plugin in one guide.

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/messaging` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capacitor-firebase/messaging firebase
npx cap sync

Add Firebase to your project if you haven't already (Android / iOS / Web).

Android

Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

• $firebaseMessagingVersion version of com.google.firebase:firebase-messaging (default: 25.0.1)

This can be useful if you encounter dependency conflicts with other plugins in your project.

Push Notification Icon

The Push Notification icon with the appropriate name should be added to the android/app/src/main/AndroidManifest.xml file:

<meta-data android:name="com.google.firebase.messaging.default_notification_icon" android:resource="@mipmap/push_icon_name" />

If no icon is specified, Android uses the application icon, but the push icon should be white pixels on a transparent background. Since the application icon does not usually look like this, it shows a white square or circle. Therefore, it is recommended to provide a separate icon for push notifications.

Prevent auto initialization

When a registration token is generated, the library uploads the identifier and configuration data to Firebase. If you prefer to prevent token autogeneration, disable Analytics collection and FCM auto initialization by adding these metadata values to the android/app/src/main/AndroidManifest.xml file:

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

iOS

Swift Package Manager

Add the following to your capacitor.config.json (or capacitor.config.ts) to avoid a SwiftPM package identity collision:

{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/messaging": {
            "symlink": true
          }
        }
      }
    }
  }
}

Attention: SPM packageOptions support requires Capacitor CLI 8.4.0+.

Setup

Important: Make sure that no other Capacitor Push Notification plugin is installed (see here).

See Prerequisites and complete the prerequisites first.

See Upload the APNS Certificate or Key to Firebase and follow the instructions to upload the APNS Certificate or APNS Auth Key to Firebase.

If you have difficulties with the instructions, you can also look at the corresponding sections of this guide.

Add the following to your app's AppDelegate.swift:

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: deviceToken)
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
  NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
}

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    NotificationCenter.default.post(name: Notification.Name.init("didReceiveRemoteNotification"), object: completionHandler, userInfo: userInfo)
}

Attention: If you use this plugin in combination with @capacitor-firebase/authentication, then add the following to your app's AppDelegate.swift:

+ import FirebaseAuth

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
+    if Auth.auth().canHandle(url) {
+      return true
+    }
    return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
}

Prevent auto initialization

When a registration token is generated, the library uploads the identifier and configuration data to Firebase. If you prefer to prevent token autogeneration, disable FCM auto initialization by editing your ios/App/App/Info.plist and set FirebaseMessagingAutoInitEnabled key to NO.

Web

1. See Configure Web Credentials with FCM and follow the instructions to configure your web credentials correctly.
2. Add a firebase-messaging-sw.js file to the root of your domain. This file can be empty if you do not want to receive push notifications in the background. See Setting notification options in the service worker for more information.

Configuration

On iOS you can configure the way the push notifications are displayed when the app is in foreground.

Examples

In capacitor.config.json:

{
  "plugins": {
    "FirebaseMessaging": {
      "presentationOptions": ["alert", "badge", "sound"]
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capacitor-firebase/messaging" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    FirebaseMessaging: {
      presentationOptions: ["alert", "badge", "sound"],
    },
  },
};

export default config;

Demo

A working example can be found here: robingenz/capacitor-firebase-plugin-demo

Starter templates

The following starter templates are available:

• Ionstarter Angular Firebase

Usage

The following examples show how to check and request notification permissions, manage the FCM token, listen for incoming notifications and their actions, subscribe to topics, and manage delivered notifications.

Check and request permissions

Check and request the permission to receive push notifications. On Android, these methods only need to be called on Android 13+:

import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const checkPermissions = async () => {
  const result = await FirebaseMessaging.checkPermissions();
  return result.receive;
};

const requestPermissions = async () => {
  const result = await FirebaseMessaging.requestPermissions();
  return result.receive;
};

Retrieve or delete the FCM token

Register the app to receive push notifications and retrieve the FCM token that can be used to send push messages to the device. Delete the token, for example when a user signs out, to stop receiving push notifications. You can also be notified when a new token is received using the tokenReceived event, which is only available on Android and iOS:

import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const getToken = async () => {
  const result = await FirebaseMessaging.getToken();
  return result.token;
};

const deleteToken = async () => {
  await FirebaseMessaging.deleteToken();
};

const addTokenReceivedListener = async () => {
  await FirebaseMessaging.addListener('tokenReceived', event => {
    console.log('tokenReceived', { event });
  });
};

Listen for incoming push notifications

Be notified when a push notification is received. If the app is in the background, this listener is only called for data push notifications on Android and for silent push notifications on iOS:

import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const addNotificationReceivedListener = async () => {
  await FirebaseMessaging.addListener('notificationReceived', event => {
    console.log('notificationReceived', { event });
  });
};

React to notification actions

Be notified when an action is performed on a push notification, for example when the user taps on it. Only available on Android and iOS:

import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const addNotificationActionPerformedListener = async () => {
  await FirebaseMessaging.addListener('notificationActionPerformed', event => {
    console.log('notificationActionPerformed', { event });
  });
};

Subscribe to topics

Subscribe to or unsubscribe from a topic to receive push messages that are sent to that topic. Only available on Android and iOS:

import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const subscribeToTopic = async () => {
  await FirebaseMessaging.subscribeToTopic({ topic: 'news' });
};

const unsubscribeFromTopic = async () => {
  await FirebaseMessaging.unsubscribeFromTopic({ topic: 'news' });
};

Manage delivered notifications

Get, remove, or clear the notifications that are currently visible on the notifications screen:

import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const getDeliveredNotifications = async () => {
  const result = await FirebaseMessaging.getDeliveredNotifications();
  return result.notifications;
};

const removeDeliveredNotifications = async () => {
  await FirebaseMessaging.removeDeliveredNotifications({
    notifications: [
      {
        id: '798dfhliblqew89pzads',
      },
    ],
  });
};

const removeAllDeliveredNotifications = async () => {
  await FirebaseMessaging.removeAllDeliveredNotifications();
};

Remove all listeners

Remove all listeners that have been added for this plugin:

import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const removeAllListeners = async () => {
  await FirebaseMessaging.removeAllListeners();
};

API

• checkPermissions()
• requestPermissions()
• isSupported()
• getToken(...)
• deleteToken()
• getDeliveredNotifications()
• removeDeliveredNotifications(...)
• removeAllDeliveredNotifications()
• subscribeToTopic(...)
• unsubscribeFromTopic(...)
• createChannel(...)
• deleteChannel(...)
• listChannels()
• addListener('tokenReceived', ...)
• addListener('notificationReceived', ...)
• addListener('notificationActionPerformed', ...)
• addListener('apnsTokenReceived', ...)
• removeAllListeners()
• Interfaces
• Type Aliases
• Enums

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check permission to receive push notifications.

On Android, this method only needs to be called on Android 13+.

Returns: Promise<PermissionStatus>

Since: 0.2.2

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permission to receive push notifications.

On Android, this method only needs to be called on Android 13+.

Returns: Promise<PermissionStatus>

Since: 0.2.2

isSupported()

isSupported() => Promise<IsSupportedResult>

Checks if all required APIs exist.

Always returns true on Android and iOS.

Returns: Promise<IsSupportedResult>

Since: 0.3.1

getToken(...)

getToken(options?: GetTokenOptions | undefined) => Promise<GetTokenResult>

Register the app to receive push notifications. Returns a FCM token that can be used to send push messages to that Messaging instance.

This method also re-enables FCM auto-init.

Returns: Promise<GetTokenResult>

Since: 0.2.2

deleteToken()

deleteToken() => Promise<void>

Delete the FCM token and unregister the app to stop receiving push notifications. Can be called, for example, when a user signs out.

Since: 0.2.2

getDeliveredNotifications()

getDeliveredNotifications() => Promise<GetDeliveredNotificationsResult>

Get a list of notifications that are visible on the notifications screen.

Note: This will return all delivered notifications, including local notifications, and not just FCM notifications.

On Android, the data field of the FCM notification will NOT be included.

Returns: Promise<GetDeliveredNotificationsResult>

Since: 0.2.2

removeDeliveredNotifications(...)

removeDeliveredNotifications(options: RemoveDeliveredNotificationsOptions) => Promise<void>

Remove specific notifications from the notifications screen.

Since: 0.2.2

removeAllDeliveredNotifications()

removeAllDeliveredNotifications() => Promise<void>

Remove all notifications from the notifications screen.

Note: This will remove all delivered notifications, including local notifications, and not just FCM notifications.

Since: 0.2.2

subscribeToTopic(...)

subscribeToTopic(options: SubscribeToTopicOptions) => Promise<void>

Subscribes to topic in the background.

Only available for Android and iOS.

Since: 0.2.2

unsubscribeFromTopic(...)

unsubscribeFromTopic(options: UnsubscribeFromTopicOptions) => Promise<void>

Unsubscribes from topic in the background.

Only available for Android and iOS.

Since: 0.2.2

createChannel(...)

createChannel(options: CreateChannelOptions) => Promise<void>

Create a notification channel.

Only available for Android (SDK 26+).

Since: 1.4.0

deleteChannel(...)

deleteChannel(options: DeleteChannelOptions) => Promise<void>

Delete a notification channel.

Only available for Android (SDK 26+).

Since: 1.4.0

listChannels()

listChannels() => Promise<ListChannelsResult>

List the available notification channels.

Only available for Android (SDK 26+).

Returns: Promise<ListChannelsResult>

Since: 1.4.0

addListener('tokenReceived', ...)

addListener(eventName: 'tokenReceived', listenerFunc: TokenReceivedListener) => Promise<PluginListenerHandle>

Called when a new FCM token is received.

Only available for Android and iOS.

Returns: Promise<PluginListenerHandle>

Since: 0.2.2

addListener('notificationReceived', ...)

addListener(eventName: 'notificationReceived', listenerFunc: NotificationReceivedListener) => Promise<PluginListenerHandle>

Called when a new push notification is received.

On Android, this listener is called for every push notification if the app is in the foreground. If the app is in the background, then this listener is only called on data push notifications. See https://firebase.google.com/docs/cloud-messaging/android/receive#handling_messages for more information.

On iOS, this listener is called for every push notification if the app is in the foreground. If the app is in the background, then this listener is only called for silent push notifications (messages with the content-available key). See https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html for more information.

Returns: Promise<PluginListenerHandle>

Since: 0.2.2

addListener('notificationActionPerformed', ...)

addListener(eventName: 'notificationActionPerformed', listenerFunc: NotificationActionPerformedListener) => Promise<PluginListenerHandle>

Called when a new push notification action is performed.

Only available for Android and iOS.

Returns: Promise<PluginListenerHandle>

Since: 0.2.2

addListener('apnsTokenReceived', ...)

addListener(eventName: 'apnsTokenReceived', listenerFunc: ApnsTokenReceivedListener) => Promise<PluginListenerHandle>

Called when the APNs token is received.

Only available for iOS.

Returns: Promise<PluginListenerHandle>

Since: 8.2.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.2.2

Interfaces

PermissionStatus

IsSupportedResult

GetTokenResult

GetTokenOptions

GetDeliveredNotificationsResult

Notification

RemoveDeliveredNotificationsOptions

SubscribeToTopicOptions

UnsubscribeFromTopicOptions

Channel

DeleteChannelOptions

ListChannelsResult

PluginListenerHandle

TokenReceivedEvent

NotificationReceivedEvent

NotificationActionPerformedEvent

ApnsTokenReceivedEvent

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

CreateChannelOptions

Channel

TokenReceivedListener

Callback to receive the token received event.

(event: TokenReceivedEvent): void

NotificationReceivedListener

Callback to receive the notification received event.

(event: NotificationReceivedEvent): void

NotificationActionPerformedListener

Callback to receive the notification action performed event.

(event: NotificationActionPerformedEvent): void

ApnsTokenReceivedListener

Callback to receive the APNs token received event.

(event: ApnsTokenReceivedEvent): void

Enums

Importance

Visibility

FAQ

What is the difference between the Capacitor Firebase Cloud Messaging plugin and the Capacitor Push Notifications plugin?

The Capacitor Push Notifications plugin supports Android (FCM) and iOS (APNs). The Capacitor Firebase Cloud Messaging plugin, on the other hand, uses the Firebase SDK for Android, iOS and Web and provides additional features such as topic subscriptions and the ability to receive notifications in the foreground.

Why is the notificationReceived listener not called when the app is in the background?

This is the expected behavior of the underlying platforms. On Android, the listener is called for every push notification only while the app is in the foreground. If the app is in the background, it is only called for data push notifications. On iOS, the listener is only called in the background for silent push notifications, which are messages with the content-available key.

Why is my push notification icon on Android displayed as a white square?

Android expects the push notification icon to consist of white pixels on a transparent background. If no dedicated icon is specified, Android falls back to the application icon, which usually does not meet this requirement and is therefore displayed as a white square or circle. Provide a separate push notification icon as described in the Installation section.

Do I need to request permissions before receiving push notifications?

Yes, use the checkPermissions() and requestPermissions() methods to check and request the permission to receive push notifications, as shown in the usage example above. On Android, these methods only need to be called on Android 13+.

Related Plugins

• Firebase Authentication: Sign in users with Firebase Authentication.
• Firebase Analytics: Log events and user properties with Firebase Analytics.
• Badge: Access and update the badge number of the app icon.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.