Capacitor Firebase Push

👉🏼 Note: this Plugin is developed for Capacitor V3

This Plugin it used for Firebase Push Messages. It does support Data (silent) notifications!

This and other Open-Source Cordova Plugins are developed in my free time. To help ensure this plugin is kept updated, new features are added and bugfixes are implemented quickly, please donate a couple of dollars (or a little more if you can stretch) as this will help me to afford to dedicate time to its maintenance. Please consider donating if you're using this plugin in an app that makes you money, if you're being paid to make the app, if you're asking for new features or priority bug fixes.

Table of Content

• Install
• Shutout
• Setup
  • Android
  • iOS
• Config
  • Push notification appearance in foreground
• API
  • checkPermissions()
  • requestPermissions()
  • register()
  • unregister()
  • getBadgeNumber()
  • setBadgeNumber(...)
  • getDeliveredNotifications()
  • removeDeliveredNotifications(...)
  • removeAllDeliveredNotifications()
  • addListener('token', ...)
  • addListener('message', ...)
  • removeAllListeners()
  • Interfaces
  • Type Aliases
• Changelog

Install

npm install capacitor-firebase-push
npx cap sync

Shutout

❤️

This Plugin was created to match every requirement I had for my app. These Plugins helped my a lot to create this one:

• cordova-plugin-firebase-x
• @capacitor/push-notifications
• @capacitor-community/fcm

Setup

Android

Just follow the Android Setup Guide here

Variables

This plugin will use the following project variables (defined in your app's variables.gradle file):

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

Push Notifications icon

On Android, the Push Notifications icon with the appropriate name should be added to the 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 will use the application icon, but push icon should be white pixels on a transparent backdrop. As the application icon is not usually like that, it will show a white square or circle. So it's recommended to provide the separate icon for Push Notifications.

Android Studio has an icon generator you can use to create your Push Notifications icon.

iOS

Start setting up your iOS Project like described here: https://capacitorjs.com/docs/v3/guides/push-notifications-firebase#integrating-firebase-with-our-native-ios-app

Stop before the Add the Firebase SDK via CocoaPods Part - we don't need that one.

After you updated the project (npx cap update ios), you have to add the following Initialization Code to your AppDelegate.swift:

1. Add the Firebase Import:

   import Firebase

2. Add the following two functions:

   func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Messaging.messaging().apnsToken = deviceToken
        Messaging.messaging().token(completion: { (token, error) in
            if let error = error {
                NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
            } else if let token = token {
                NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: token)
            }
        })
    }
   
    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)
    }

Config

Push notification appearance in foreground

On iOS you can configure the way the push notifications are displayed when the app is in foreground by providing the `presentationOptions in your capacitor.config.ts as an Array of Strings you can combine.

Possible values are:

• badge: badge count on the app icon is updated (default value)
• sound: the device will ring/vibrate when the push notification is received
• alert: the push notification is displayed in a native dialog

An empty Array can be provided if none of the previous options are desired. pushNotificationReceived event will still be fired with the push notification information.

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

These fields can be overwritten if you pass create_notification: true in the data Part of the notification.

API

• checkPermissions()
• requestPermissions()
• register()
• unregister()
• getBadgeNumber()
• setBadgeNumber(...)
• getDeliveredNotifications()
• removeDeliveredNotifications(...)
• removeAllDeliveredNotifications()
• addListener('token', ...)
• addListener('message', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check permission to receive push notifications.

Will always return "granted" on Android

Returns: Promise<PermissionStatus>

Since: 1.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permission to receive push notifications.

Will always return "granted" on Android

Returns: Promise<PermissionStatus>

Since: 1.0.0

register()

register() => Promise<void>

Register the app to receive push notifications.

Since: 1.0.0

unregister()

unregister() => Promise<void>

Should be called to unregister the Firebase Instance. For example if a User logs out.

Since: 1.1.0

getBadgeNumber()

getBadgeNumber() => Promise<BadgeCount>

Get icon badge Value

Only available on iOS

Returns: Promise<BadgeCount>

Since: 1.2.0

setBadgeNumber(...)

setBadgeNumber(options: BadgeCount) => Promise<void>

Set icon badge Value

Only available on iOS

| Param | Type | | ------------- | ------------------------------------------------- | | options | BadgeCount |

Since: 1.2.0

getDeliveredNotifications()

getDeliveredNotifications() => Promise<NotificationsResult>

Get notifications in Notification Center

Returns: Promise<NotificationsResult>

Since: 1.2.0

removeDeliveredNotifications(...)

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

Remove notifications from the notifications screen based on the id

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | NotificationsIds |

Since: 1.2.0

removeAllDeliveredNotifications()

removeAllDeliveredNotifications() => Promise<void>

Remove all notifications from the notifications screen

Since: 1.2.0

addListener('token', ...)

addListener(eventName: 'token', listenerFunc: (result: TokenResult) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Called when a new fcm token is created

| Param | Type | | ------------------ | ------------------------------------------------------------------------ | | eventName | 'token' | | listenerFunc | (result: TokenResult) => void |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 1.0.0

addListener('message', ...)

addListener(eventName: 'message', listenerFunc: (message: any) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Called when a new message is received

| Param | Type | | ------------------ | -------------------------------------- | | eventName | 'message' | | listenerFunc | (message: any) => void |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all native listeners for this plugin.

Since: 1.0.0

Interfaces

PermissionStatus

| Prop | Type | Since | | ------------- | ----------------------------------------------------------- | ----- | | receive | PermissionState | 1.0.0 |

BadgeCount

| Prop | Type | Since | | ----------- | ------------------- | ----- | | count | number | 1.2.0 |

NotificationsResult

| Prop | Type | Since | | ------------------- | ------------------ | ----- | | notifications | any[] | 1.2.0 |

NotificationsIds

| Prop | Type | Since | | --------- | --------------------- | ----- | | ids | string[] | 1.2.0 |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

TokenResult

| Prop | Type | | ----------- | ------------------- | | token | string |

Type Aliases

PermissionState

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

Changelog

The full Changelog is available here