README

Cordova plugin for Firebase Cloud Messaging

| | Your help is appreciated. Create a PR, submit a bug or just grab me :beer: | |-|-|

Index

Supported platforms
Installation
Adding configuration files
Methods
Notification channels on Android 8+
Android tips

Supported platforms

iOS
Android

Installation

$ cordova plugin add cordova-plugin-firebase-messaging

If you get an error about CocoaPods being unable to find compatible versions, run

$ pod repo update

Use variables IOS_FIREBASE_POD_VERSION, ANDROID_FIREBASE_MESSAGING_VERSION and ANDROIDX_CORE_VERSION to override dependency versions on Android:

$ cordova plugin add cordova-plugin-firebase-messaging --variable IOS_FIREBASE_POD_VERSION="~> 8.8.0" --variable ANDROID_FIREBASE_MESSAGING_VERSION="22.0.+" --variable ANDROIDX_CORE_VERSION="1.6.+"

Adding configuration files

Cordova supports resource-file tag for easy copying resources files. Firebase SDK requires google-services.json on Android and GoogleService-Info.plist on iOS platforms.

Put google-services.json and/or GoogleService-Info.plist into the root directory of your Cordova project
Add new tag for Android platform

<platform name="android">
    ...
    <resource-file src="google-services.json" target="app/google-services.json" />
</platform>
...
<platform name="ios">
    ...
    <resource-file src="GoogleService-Info.plist" />
</platform>

This way config files will be copied on cordova prepare step.

Methods

In general (for both platforms) you can only rely on custom data fields from a FCM payload.

For iOS APNS payload is stored in aps object. It's available when a message arrives in both foreground and background.

For Android GCM payload is stored in gcm. It's available ONLY when a message arrives in foreground. For a some reason Google applied this limitation into their APIs. Anyway I've created an issue for a future improvement.

onMessage(callback)

Called when a push message received while app is in foreground.

cordova.plugins.firebase.messaging.onMessage(function(payload) {
    console.log("New foreground FCM message: ", payload);
});

NOTE: on iOS make sure notification payload contains key content-available with value 1. Otherwise this callback is never fired.

onBackgroundMessage(callback)

Called when a push message received while app is in background.

cordova.plugins.firebase.messaging.onBackgroundMessage(function(payload) {
    console.log("New background FCM message: ", payload);
});

NOTE: on iOS make sure notification payload contains key content-available with value 1. Otherwise this callback is never fired.

requestPermission(options)

Grant permission to recieve push notifications (will trigger prompt on iOS).

cordova.plugins.firebase.messaging.requestPermission().then(function() {
    console.log("Push messaging is allowed");
});

In options object you can specify a boolean setting forceShow. When true this setting forces notification to display even when app is in foreground:

cordova.plugins.firebase.messaging.requestPermission({forceShow: true}).then(function() {
    console.log("You'll get foreground notifications when a push message arrives");
});

getToken(type)

Returns a promise that fulfills with the current FCM token.

cordova.plugins.firebase.messaging.getToken().then(function(token) {
    console.log("Got device token: ", token);
});

This method also accepts optional argument type. Currently iOS platform supports values "apns-buffer" and "apns-string" that defines presentation of resolved APNS token:

cordova.plugins.firebase.messaging.getToken("apns-string").then(function(token) {
    console.log("APNS hex device token: ", token);
});

clearNotifications

Clear all notifications from system notification bar.

cordova.plugins.firebase.messaging.clearNotifications(function() {
    console.log("Notification messages cleared successfully");
});

deleteToken

Delete the Instance ID (Token) and the data associated with it. Call getToken to generate a new one.

cordova.plugins.firebase.messaging.deleteToken().then(function() {
    console.log("Token revoked successfully");
});

onTokenRefresh(callback)

Triggers every time when FCM token updated. You should usually call getToken to get an updated token and send it to server.

cordova.plugins.firebase.messaging.onTokenRefresh(function() {
    console.log("Device token updated");
});

Use this callback to get initial token and to refresh stored value in future.

subscribe(topic)

Subscribe to a topic in background.

cordova.plugins.firebase.messaging.subscribe("New Topic");

unsubscribe(topic)

Unsubscribe from a topic in background.

cordova.plugins.firebase.messaging.unsubscribe("New Topic");

getBadge

Reads current badge number (if supported).

cordova.plugins.firebase.messaging.getBadge().then(function(value) {
    console.log("Badge value: ", value);
});

setBadge(value)

Sets current badge number (if supported).

cordova.plugins.firebase.messaging.setBadge(value);

Notification channels on Android 8+

Starting in Android 8.0 (API level 26), all notifications must be assigned to a channel or it will not appear. By categorizing notifications into channels, users can disable specific notification channels for your app (instead of disabling all your notifications), and users can control the visual and auditory options for each channel—all from the Android system settings.

On devices running Android 7.1 (API level 25) and lower methods below does not work.

createChannel(options)

Creates a notification channel that notifications can be posted to.

cordova.plugins.firebase.messaging.createChannel({
    id: "custom_channel_id",
    name: "Custom channel",
    importance: 0
});

Channel options

Property	Type	Description
`id`	`String`	The id of the channel. Must be unique per package.
`name`	`String`	User visible name of the channel.
`description`	`String`	User visible description of this channel.
`importance`	`Integer`	The importance of the channel. This controls how interruptive notifications posted to this channel are. The importance property goes from 1 = Lowest, 2 = Low, 3 = Normal, 4 = High and 5 = Highest.
`sound`	`String`	The name of the sound file to be played upon receipt of the notification in this channel. Cannot be changed after channel is created.
`badge`	`Boolean`	Sets whether notifications posted to this channel can appear as application icon badges in a Launcher.
`light`	`Boolean`	Sets whether notifications posted to this channel should display notification lights, on devices that support that feature.
`lightColor`	`Integer`	Sets the notification light color #RGBA for notifications posted to this channel.
`vibration`	`Boolean` or `Array`	Sets whether notification posted to this channel should vibrate. Pass array value instead of a boolean to set a vibration pattern.

findChannel(channelId)

Returns the notification channel settings for a given channel id.

cordova.plugins.firebase.messaging.findChannel(channelId).then(function(channel) {
    console.log(channel);
});

listChannels()

Returns all notification channels belonging to the app.

cordova.plugins.firebase.messaging.listChannels().then(function(channels) {
    console.log(channels);
});

deleteChannel(channelId)

Deletes the given notification channel.

cordova.plugins.firebase.messaging.deleteChannel(channelId);

Android tips

Set custom default notification icon

Setting a custom default icon allows you to specify what icon is used for notification messages if no icon is set in the notification payload. Also use the custom default icon to set the icon used by notification messages sent from the Firebase console. If no custom default icon is set and no icon is set in the notification payload, the application icon (rendered in white) is used.

<config-file parent="/manifest/application" target="app/src/main/AndroidManifest.xml">
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_icon"
        android:resource="@drawable/my_custom_icon_id"/>
</config-file>

Set custom default notification color

You can also define what color is used with your notification. Different android versions use this settings in different ways: Android < N use this as background color for the icon. Android >= N use this to color the icon and the app name.

<config-file parent="/manifest/application" target="app/src/main/AndroidManifest.xml">
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_color"
        android:resource="@drawable/my_custom_color"/>
</config-file>

Usage no npm install needed!