cordova-plugin-firebasex
Version:
Cordova plugin for Google Firebase
1,084 lines (880 loc) • 59.6 kB
Markdown
cordova-plugin-firebasex [](https://www.npmjs.com/package/cordova-plugin-firebasex) [](https://npm-stat.com/charts.html?package=cordova-plugin-firebasex)
========================
This plugin is a fork of [cordova-plugin-firebase](https://github.com/arnesson/cordova-plugin-firebase) which has been rework to fix issues and add new functionality.
It brings push notifications, analytics, event tracking, crash reporting and more from Google Firebase to your Cordova project.
Supported platforms: Android and iOS
<!-- DONATE -->
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ZRD3W47HQ3EMJ)
I dedicate a considerable amount of my free time to developing and maintaining this Cordova plugin, along with my other Open Source software.
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.
<!-- END DONATE -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**
- [Installation](#installation)
- [Supported Cordova Versions](#supported-cordova-versions)
- [Migrating from cordova-plugin-firebase](#migrating-from-cordova-plugin-firebase)
- [Build environment notes](#build-environment-notes)
- [Specifying dependent library versions](#specifying-dependent-library-versions)
- [PhoneGap Build](#phonegap-build)
- [Android-specific](#android-specific)
- [AndroidX](#androidx)
- [Google Play Services and Firebase libraries](#google-play-services-and-firebase-libraries)
- [iOS-specific](#ios-specific)
- [iOS minimum version](#ios-minimum-version)
- [Cocoapods](#cocoapods)
- [Strip debug symbols](#strip-debug-symbols)
- [Firebase config setup](#firebase-config-setup)
- [Example project](#example-project)
- [Reporting issues](#reporting-issues)
- [Cloud messaging](#cloud-messaging)
- [Background notifications](#background-notifications)
- [Foreground notifications](#foreground-notifications)
- [Android notifications](#android-notifications)
- [Android background notifications](#android-background-notifications)
- [Android foreground notifications](#android-foreground-notifications)
- [Android Notification Channels](#android-notification-channels)
- [Android Notification Icons](#android-notification-icons)
- [Android Default Notification Icon](#android-default-notification-icon)
- [Android Large Notification Icon](#android-large-notification-icon)
- [Android Custom Notification Icons](#android-custom-notification-icons)
- [Android Notification Color](#android-notification-color)
- [Android Notification Sound](#android-notification-sound)
- [iOS notifications](#ios-notifications)
- [iOS notification sound](#ios-notification-sound)
- [iOS badge number](#ios-badge-number)
- [Data messages](#data-messages)
- [Data message notifications](#data-message-notifications)
- [Android data message notifications](#android-data-message-notifications)
- [iOS data message notifications](#ios-data-message-notifications)
- [Google Tag Manager](#google-tag-manager)
- [Android](#android)
- [iOS](#ios)
- [API](#api)
- [Notifications and data messages](#notifications-and-data-messages)
- [getToken](#gettoken)
- [onTokenRefresh](#ontokenrefresh)
- [onMessageReceived](#onmessagereceived)
- [grantPermission](#grantpermission)
- [hasPermission](#haspermission)
- [unregister](#unregister)
- [setBadgeNumber](#setbadgenumber)
- [getBadgeNumber](#getbadgenumber)
- [clearAllNotifications](#clearallnotifications)
- [subscribe](#subscribe)
- [unsubscribe](#unsubscribe)
- [createChannel](#createchannel)
- [setDefaultChannel](#setdefaultchannel)
- [Default Android Channel Properties](#default-android-channel-properties)
- [deleteChannel](#deletechannel)
- [listChannels](#listchannels)
- [Analytics](#analytics)
- [setAnalyticsCollectionEnabled](#setanalyticscollectionenabled)
- [logEvent](#logevent)
- [setScreenName](#setscreenname)
- [setUserId](#setuserid)
- [setUserProperty](#setuserproperty)
- [Crashlytics](#crashlytics)
- [setCrashlyticsUserId](#setcrashlyticsuserid)
- [sendCrash](#sendcrash)
- [logMessage](#logmessage)
- [logError](#logerror)
- [Authentication](#authentication)
- [verifyPhoneNumber](#verifyphonenumber)
- [Android](#android-1)
- [iOS](#ios-1)
- [Remote Config](#remote-config)
- [fetch](#fetch)
- [activateFetched](#activatefetched)
- [getValue](#getvalue)
- [getByteArray](#getbytearray)
- [getInfo](#getinfo)
- [setConfigSettings](#setconfigsettings)
- [setDefaults](#setdefaults)
- [Performance](#performance)
- [startTrace](#starttrace)
- [incrementCounter](#incrementcounter)
- [stopTrace](#stoptrace)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Installation
Install the plugin by adding it to your project's config.xml:
```
<plugin name="cordova-plugin-firebasex" spec="latest" />
```
or by running:
```
cordova plugin add cordova-plugin-firebasex
```
### Supported Cordova Versions
- cordova: `>= 8`
- cordova-android: `>= 8`
- cordova-ios: `>= 4`
### Migrating from cordova-plugin-firebase
If you already have [cordova-plugin-firebase](https://github.com/arnesson/cordova-plugin-firebase) installed in your Cordova project, you need to completely remove it before installing this plugin otherwise they will conflict and cause build errors in your project. The safest way of doing this is as follows:
rm -Rf platforms/android
cordova plugin rm cordova-plugin-firebase
rm -Rf plugins/ node_modules/
npm install
cordova plugin add cordova-plugin-firebasex
cordova platform add android
**IMPORTANT:** Recent versions of `cordova-plugin-firebasex` have made breaking changes to the plugin API in order to fix bugs or add more functionality.
Therefore you can no longer directly substitute `cordova-plugin-firebasex` in place of `cordova-plugin-firebase` without making code changes.
Please see the `CHANGELOG.md` for a list of breaking changes and see this plugin's documentation below for current API features.
## Build environment notes
### Specifying dependent library versions
This plugin depends on various components such as the Firebase SDK which are pulled in at build-time by Gradle on Android and Cocoapods on iOS.
By default this plugin pins specific versions of these in [its `plugin.xml`](https://github.com/dpa99c/cordova-plugin-firebase/blob/master/plugin.xml) where you can find the currently pinned Android & iOS versions as `<preference>`'s, for example:
<preference name="ANDROID_FIREBASE_CORE_VERSION" default="17.0.0" />
These defaults can be overridden at plugin installation time by specifying plugin variables as command-line arguments, for example:
cordova plugin add cordova-plugin-firebasex --variable ANDROID_FIREBASE_CORE_VERSION=17.0.0
Or you can specify them as plugin variables in your `config.xml`, for example:
<plugin name="cordova-plugin-firebasex" spec="latest">
<variable name="ANDROID_FIREBASE_CORE_VERSION" value="17.0.0" />
</plugin>
The following plugin variables are use to specify the follow Gradle dependency versions on Android:
- `ANDROID_PLAY_SERVICES_TAGMANAGER_VERSION` => `com.google.android.gms:play-services-tagmanager`
- `ANDROID_FIREBASE_CORE_VERSION` => `com.google.firebase:firebase-core`
- `ANDROID_FIREBASE_MESSAGING_VERSION` => `com.google.firebase:firebase-messaging`
- `ANDROID_FIREBASE_CONFIG_VERSION` => `com.google.firebase:firebase-config`
- `ANDROID_FIREBASE_PERF_VERSION` => `com.google.firebase:firebase-perf`
- `ANDROID_FIREBASE_AUTH_VERSION` => `com.google.firebase:firebase-auth`
- `ANDROID_CRASHLYTICS_VERSION` => `com.crashlytics.sdk.android:crashlytics`
- `ANDROID_CRASHLYTICS_NDK_VERSION` => `com.crashlytics.sdk.android:crashlytics-ndk`
- `ANDROID_SHORTCUTBADGER_VERSION` => `me.leolin:ShortcutBadger`
The following plugin variables are use to specify the follow Cocoapods dependency versions on iOS:
- `IOS_FIREBASE_CORE_VERSION` => `Firebase/Core`
- `IOS_FIREBASE_AUTH_VERSION` => `Firebase/Auth`
- `IOS_FIREBASE_MESSAGING_VERSION` => `Firebase/Messaging`
- `IOS_FIREBASE_PERFORMANCE_VERSION` => `Firebase/Performance`
- `IOS_FIREBASE_REMOTECONFIG_VERSION` => `Firebase/RemoteConfig`
- `IOS_FABRIC_VERSION` => `Fabric`
- `IOS_CRASHLYTICS_VERSION` => `Crashlytics`
For example, to explicitly specify all the component versions at plugin install time:
cordova plugin add cordova-plugin-firebasex \
--variable ANDROID_PLAY_SERVICES_TAGMANAGER_VERSION=17.0.0 \
--variable ANDROID_FIREBASE_CORE_VERSION=17.0.0 \
--variable ANDROID_FIREBASE_MESSAGING_VERSION=19.0.0 \
--variable ANDROID_FIREBASE_CONFIG_VERSION=18.0.0 \
--variable ANDROID_FIREBASE_PERF_VERSION=18.0.0 \
--variable ANDROID_FIREBASE_AUTH_VERSION=18.0.0 \
--variable ANDROID_CRASHLYTICS_VERSION=2.10.1 \
--variable ANDROID_CRASHLYTICS_NDK_VERSION=2.1.0 \
--variable ANDROID_SHORTCUTBADGER_VERSION=1.1.22 \
--variable IOS_FIREBASE_CORE_VERSION=5.20.2 \
--variable IOS_FIREBASE_AUTH_VERSION=5.20.2 \
--variable IOS_FIREBASE_MESSAGING_VERSION=5.20.2 \
--variable IOS_FIREBASE_PERFORMANCE_VERSION=5.20.2 \
--variable IOS_FIREBASE_REMOTECONFIG_VERSION=5.20.2 \
--variable IOS_FABRIC_VERSION=1.9.0 \
--variable IOS_CRASHLYTICS_VERSION=3.12.0
### PhoneGap Build
This plugin will not work with Phonegap Build (and other remote cloud build envs) do not support Cordova hook scripts as they are used by this plugin to configure the native platform projects.
### Android-specific
#### AndroidX
This plugin has been migrated to use [AndroidX (Jetpack)](https://developer.android.com/jetpack/androidx/migrate) which is the successor to the [Android Support Library](https://developer.android.com/topic/libraries/support-library/index).
This is implemented by adding a dependency on [cordova-plugin-androidx](https://github.com/dpa99c/cordova-plugin-androidx) which enables AndroidX in the Android platform of a Cordova project.
This is because the [major release of the Firebase and Play Services libraries on 17 June 2019](https://developers.google.com/android/guides/releases#june_17_2019) were migrated to AndroidX.
Therefore if your project includes any plugins which are dependent on the legacy Android Support Library, you should add [cordova-plugin-androidx-adapter](https://github.com/dpa99c/cordova-plugin-androidx-adapter) to your project.
This plugin will dynamically migrate any plugin code from the Android Support Library to AndroidX equivalents.
### Google Play Services and Firebase libraries
Your Android build may fail if you are installing multiple plugins that use the Google Play Services library.
This is caused by plugins installing different versions of the Google Play Services library.
This can be resolved by installing [cordova-android-play-services-gradle-release](https://github.com/dpa99c/cordova-android-play-services-gradle-release) which enables you to override the versions specified by other plugins in order to align them.
Similarly, if your build is failing because multiple plugins are installing different versions of the Firebase library,
you can try installing [cordova-android-firebase-gradle-release](https://github.com/dpa99c/cordova-android-firebase-gradle-release) to align these.
### iOS-specific
#### iOS minimum version
This plugin sets a default minimum iOS version in the Pod file (see `<preference name="IOS_MIN_VERSION">` in `plugin.xml`) which can be overriden using a plugin variable of the same name, e.g.:
cordova plugin add cordova-plugin-firebasex --variable IOS_MIN_VERSION=10.0
#### Cocoapods
This plugin relies on `cordova@9`/`cordova-ios@5` support for the [CocoaPods dependency manager]( https://cocoapods.org/) in order to satify the iOS Firebase SDK library dependencies.
Therefore please make sure you have Cocopods installed in your iOS build environemnt - setup instructions can be found [here](https://cocoapods.org/).
Also make sure your local Cocoapods repo is up-to-date by running `pod repo update`.
If building your project in Xcode, you need to open `YourProject.xcworkspace` (not `YourProject.xcodeproj`) so both your Cordova app project and the Pods project will be loaded into Xcode.
You can list the pod dependencies in your Cordova iOS project by installing [cocoapods-dependencies](https://github.com/segiddins/cocoapods-dependencies):
sudo gem install cocoapods-dependencies
cd platforms/ios/
pod dependencies
#### Strip debug symbols
If your iOS app build contains too many debug symbols (i.e. because you include lots of libraries via a Cocoapods), you might get an error (e.g. [issue #28](https://github.com/dpa99c/cordova-plugin-firebase/issues/28)) when you upload your binary to App Store Connect, e.g.:
ITMS-90381: Too many symbol files - These symbols have no corresponding slice in any binary [16EBC8AC-DAA9-39CF-89EA-6A58EB5A5A2F.symbols, 1B105D69-2039-36A4-A04D-96C1C5BAF235.symbols, 476EACDF-583B-3B29-95B9-253CB41097C8.symbols, 9789B03B-6774-3BC9-A8F0-B9D44B08DCCB.symbols, 983BAE60-D245-3291-9F9C-D25E610846AC.symbols].
To prevent this, you can set the `IOS_STRIP_DEBUG` plugin variable which prevents symbolification of all libraries included via Cocoapods (see here)[https://stackoverflow.com/a/48518656/777265]:
cordova plugin add cordova-plugin-firebasex --variable IOS_STRIP_DEBUG=true
By default this preference is set to `false`.
Note: if you enable this setting, any crashes that occur within libraries included via Cocopods will not be recorded in Crashlytics or other crash reporting services.
## Firebase config setup
There's a handy [installation and setup guide on medium.com](https://medium.com/@felipepucinelli/how-to-add-push-notifications-in-your-cordova-application-using-firebase-69fac067e821).
However, if using this, remember this forked plugin is `cordova-plugin-firebasex` (not `cordova-plugin-firebase`).
Download your Firebase configuration files, `GoogleService-Info.plist` for iOS and `google-services.json` for android, and place them in the root folder of your cordova project.
Check out this [firebase article](https://support.google.com/firebase/answer/7015592) for details on how to download the files.
```
- My Project/
platforms/
plugins/
www/
config.xml
google-services.json <--
GoogleService-Info.plist <--
...
```
IMPORTANT: The Firebase SDK requires the configuration files to be present and valid, otherwise your app will crash on boot or Firebase features won't work.
## Example project
An example project repo exists to demonstrate and validate the functionality of this plugin:
https://github.com/dpa99c/cordova-plugin-firebasex-test
Please use this as a working reference.
## Reporting issues
Before reporting an issue with this plugin, please do the following:
- check a similar issue is not already open (or closed) against this plugin.
- try to reproduce the issue using the example project
- or if that's not possible, using an isolated test project that you are able to share
- this will eliminate bugs in your code or conflicts with other code as possible causes of the issue
- any issue which is suspected of being caused by the Ionic Native wrapper should be [reported against Ionic Native](https://github.com/ionic-team/ionic-native/issues/new)
- Ionic Native Typescript wrappers are maintained by the Ionic Team
- To verify an if an issue is caused by this plugin or its Typescript wrapper, please re-test using the vanilla Javascript plugin interface (without the Ionic Native wrapper).
- if you are having build problems, ensure you have thoroughly read the [Build environment notes](#build-environment-notes) section and searched existing open/closed issues for a similar problem.
- if you are migrating from `cordova-plugin-firebase` to `cordova-plugin-firebasex` please make sure you have read the [Migrating from cordova-plugin-firebase](#migrating-from-cordova-plugin-firebase) section.
## Cloud messaging
There are 2 distinct types of messages that can be sent by Firebase Cloud Messaging (FCM):
- [Notification messages](https://firebase.google.com/docs/cloud-messaging/concept-options#notifications)
- automatically displayed to the user by the operating system on behalf of the client app **while your app is not running or is in the background**
- **if your app is in the foreground when the notification message arrives**, it is passed to the client app and it is the responsibility of the client app to display it.
- have a predefined set of user-visible keys and an optional data payload of custom key-value pairs.
- [Data messages](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages)
- Client app is responsible for processing data messages.
- Data messages have only custom key-value pairs.
Note: only notification messages can be sent via the Firebase Console - data messages must be sent via the [FCM APIs](https://firebase.google.com/docs/cloud-messaging/server).
### Background notifications
If the notification message arrives while the app is in the background/not running, it will be displayed as a system notification.
No callback can be made by the plugin to the app when the message arrives since the display of the notification is entirely handled by the operating system.
However if the user taps the system notification, this launches/resumes the app and the notification title, body and optional data payload is passed to the [onMessageReceived](#onMessageReceived) callback.
When the `onMessageReceived` is called in response to a user tapping a system notification, it will be passed the property `tap: true`.
### Foreground notifications
If the notification message arrives while the app is in running in the foreground, by default **it will NOT be displayed as a system notification**.
Instead the notification message payload will be passed to the [onMessageReceived](#onMessageReceived) callback for the plugin to handle.
When the `onMessageReceived` is called in response to a foreground notification, it will be passed the property `tap: false`.
If you include the `notification_foreground` key in the `data` payload, the plugin will also display a system notification upon receiving the notification messages while the app is running in the foreground.
For example:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"data": {
"notification_foreground": "true",
}
}
You can set additional properties of the foreground notification using the same key names as for [Data Message Notifications](#data-message-notification-keys).
### Android notifications
Notifications on Android can be customised to specify the sound, icon, LED colour, etc. that's displayed when the notification arrives.
#### Android background notifications
If the notification message arrives while the app is in the background/not running, it will be displayed as a system notification.
In addition to the title and body of the notification message, Android system notifications support specification of the following notification settings:
- [Icon](#android-notification-icons)
- [Sound](#android-notification-sound)
- [Color accent](#android-notification-color)
- [Channel ID](#android-notification-channels) (Android 8.0 (O) and above)
- This channel configuration enables you to specify:
- Sound
- Vibration
- LED light
- Badge
- Importance
- Visibility
- See [createChannel](#createchannel) for details.
#### Android foreground notifications
If the notification message arrives while the app is in the foreground, by default a system notification won't be displayed and the data will be passed to [onMessageReceived](#onMessageReceived).
However, if you set the `notification_foreground` key in the `data` section of the notification message payload, this will cause the plugin to display system notification when the message is received while your app is in the foreground. You can customise the notification using the same keys as for [Android data message notifications](#android-data-message-notifications).
#### Android Notification Channels
- Android 8 (O) introduced [notification channels](https://developer.android.com/training/notify-user/channels).
- Notification channels are configured by the app and used to determine the sound/lights/vibration settings of system notifications.
- By default, this plugin creates a default channel with [default properties]((#default-android-channel-properties)
- These can be overridden via the [setDefaultChannel](#setdefaultchannel) function.
- The plugin enables the creation of additional custom channels via the [createChannel](#createchannel) function.
On Android 7 and below, the sound setting of system notifications is specified in the notification message itself, for example:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"android": {
"notification": {
"sound": "crystal",
"tag": "default"
}
}
#### Android Notification Icons
By default the plugin will use the default app icon for notification messages.
##### Android Default Notification Icon
To define a custom default notification icon, you need to create the images and deploy them to the `<projectroot>/platforms/android/app/src/main/res/<drawable-DPI>` folders.
The easiest way to do this is using the [Image Asset Studio in Android Studio](https://developer.android.com/studio/write/image-asset-studio#create-notification) or using the [Android Asset Studio webapp](https://romannurik.github.io/AndroidAssetStudio/icons-notification.html#source.type=clipart&source.clipart=ac_unit&source.space.trim=1&source.space.pad=0&name=notification_icon).
The icons should be monochrome transparent PNGs with the following sizes:
- mdpi: 24x24
- hdpi: 36x36
- xhdpi: 48x48
- xxhdpi: 72x72
- xxxhdpi: 96x96
Once you've created the images, you need to deploy them from your Cordova project to the native Android project.
To do this, copy the `drawable-DPI` image directories into your Cordova project and add `<resource-file>` entries to the `<platform name="android">` section of your `config.xml`, for example:
<platform name="android">
<resource-file src="res/android/drawable-mdpi/notification_icon.png" target="app/src/main/res/drawable-mdpi/notification_icon.png" />
<resource-file src="res/android/drawable-hdpi/notification_icon.png" target="app/src/main/res/drawable-hdpi/notification_icon.png" />
<resource-file src="res/android/drawable-xhdpi/notification_icon.png" target="app/src/main/res/drawable-xhdpi/notification_icon.png" />
<resource-file src="res/android/drawable-xxhdpi/notification_icon.png" target="app/src/main/res/drawable-xxhdpi/notification_icon.png" />
<resource-file src="res/android/drawable-xxxhdpi/notification_icon.png" target="app/src/main/res/drawable-xxxhdpi/notification_icon.png" />
</platform>
The default notification icon images **must** be named `notification_icon.png`.
You then need to add a `<config-file>` block to the `config.xml` which will instruct Firebase to use your icon as the default for notifications:
<platform name="android">
<config-file target="AndroidManifest.xml" parent="application">
<meta-data android:name="com.google.firebase.messaging.default_notification_icon" android:resource="@drawable/notification_icon" />
</config-file>
</platform>
##### Android Large Notification Icon
The default notification icons above are monochrome, however you can additionally define a larger multi-coloured icon.
**NOTE:** FCM currently does not support large icons in system notifications displayed for notification messages received in the while the app is in the background (or not running).
So the large icon will currently only be used if specified in [data messages](#android-data-messages) or [foreground notifications](#foreground-notifications).
The large icon image should be a PNG-24 that's 256x256 pixels and must be named `notification_icon_large.png` and should be placed in the `drawable-xxxhdpi` resource directory.
As with the small icons, you'll need to add a `<resource-file>` entry to the `<platform name="android">` section of your `config.xml`:
<platform name="android">
<resource-file src="res/android/drawable-xxxhdpi/notification_icon_large.png" target="app/src/main/res/drawable-xxxhdpi/notification_icon_large.png" />
</platform>
##### Android Custom Notification Icons
You can define additional sets of notification icons in the same manner as above.
These can be specified in notification or data messages.
For example:
<resource-file src="res/android/drawable-mdpi/my_icon.png" target="app/src/main/res/drawable-mdpi/my_icon.png" />
<resource-file src="res/android/drawable-hdpi/my_icon.png" target="app/src/main/res/drawable-hdpi/my_icon.png" />
<resource-file src="res/android/drawable-xhdpi/my_icon.png" target="app/src/main/res/drawable-xhdpi/my_icon.png" />
<resource-file src="res/android/drawable-xxhdpi/my_icon.png" target="app/src/main/res/drawable-xxhdpi/my_icon.png" />
<resource-file src="res/android/drawable-xxxhdpi/my_icon.png" target="app/src/main/res/drawable-xxxhdpi/my_icon.png" />
<resource-file src="res/android/drawable-xxxhdpi/my_icon_large.png" target="app/src/main/res/drawable-xxxhdpi/my_icon_large.png" />
When sending an FCM notification message, you will then specify the icon name in the `android.notification` section, for example:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"android": {
"notification": {
"icon": "my_icon",
}
},
"data": {
"notification_foreground": "true",
}
}
You can also reference these icons in [data messages](#android-data-messages), for example:
{
"name": "my_data",
"data" : {
"notification_foreground": "true",
"notification_body" : "Notification body",
"notification_title": "Notification title",
"notification_android_icon": "my_icon",
}
}
#### Android Notification Color
On Android Lollipop (5.0/API 21) and above you can set the default accent color for the notification by adding a color setting.
This is defined as an [ARGB colour](https://en.wikipedia.org/wiki/RGBA_color_space#ARGB_(word-order)) which the plugin sets by default to `#FF00FFFF` (cyan).
You can override this default by specifying a value using the `ANDROID_ICON_ACCENT` plugin variable during plugin installation, for example:
cordova plugin add cordova-plugin-firebasex --variable ANDROID_ICON_ACCENT=#FF123456
You can override the default color accent by specifying the `colour` key as an RGB value in a notification message, e.g.:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"android": {
"notification": {
"color": "#00ff00"
}
}
}
And in a data message:
{
"name": "my_data",
"data" : {
"notification_foreground": "true",
"notification_body" : "Notification body",
"notification_title": "Notification title",
"notification_android_color": "#00ff00"
}
}
#### Android Notification Sound
You can specify custom sounds for notifications or play the device default notification sound.
Custom sound files must be in `.mp3` format and deployed to the `/res/raw` directory in the Android project.
To do this, you can add `<resource-file>` tags to your `config.xml` to deploy the files, for example:
<platform name="android">
<resource-file src="res/android/raw/my_sound.mp3" target="app/src/main/res/raw/my_sound.mp3" />
</platform>
In a notification message, you specify the sound file name in the `android.notification` section, for example:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"android": {
"notification": {
"sound": "crystal"
}
}
}
And in a data message by specifying it in the `data` section:
{
"name": "my_data",
"data" : {
"notification_foreground": "true",
"notification_body" : "Notification body",
"notification_title": "Notification title",
"notification_android_sound": "crystal"
}
}
- To play the default notification sound, set `"sound": "default"`.
- To display a silent notification (no sound), omit the `sound` key from the message.
### iOS notifications
Notifications on iOS can be customised to specify the sound and badge number that's displayed when the notification arrives.
Notification settings are specified in the `apns.payload.aps` key of the notification message payload.
For example:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"apns": {
"payload": {
"aps": {
"sound": "default",
"badge": 1
}
}
}
}
#### iOS notification sound
You can specify custom sounds for notifications or play the device default notification sound.
Custom sound files must be in a supported audio format (see [this Apple documentation](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/SupportingNotificationsinYourApp.html#//apple_ref/doc/uid/TP40008194-CH4-SW10) for supported formats).
For example to convert an `.mp3` file to the supported `.caf` format run:
afconvert my_sound.mp3 my_sound.caf -d ima4 -f caff -v
Sound files must be deployed with the iOS application bundle.
To do this, you can add `<resource-file>` tags to your `config.xml` to deploy the files, for example:
<platform name="ios">
<resource-file src="res/ios/sound/my_sound.caf" />
</platform>
In a notification message, specify the `sound` key in the `apns.payload.aps` section, for example:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"apns": {
"payload": {
"aps": {
"sound": "my_sound.caf"
}
}
}
}
- To play the default notification sound, set `"sound": "default"`.
- To display a silent notification (no sound), omit the `sound` key from the message.
In a data message, specify the `notification_ios_sound` key in the `data` section:
{
"name": "my_data",
"data" : {
"notification_foreground": "true",
"notification_body" : "Notification body",
"notification_title": "Notification title",
"notification_ios_sound": "my_sound.caf"
}
}
#### iOS badge number
In a notification message, specify the `badge` key in the `apns.payload.aps` section, for example:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"apns": {
"payload": {
"aps": {
"badge": 1
}
}
}
}
In a data message, specify the `notification_ios_badge` key in the `data` section:
{
"name": "my_data",
"data" : {
"notification_foreground": "true",
"notification_body" : "Notification body",
"notification_title": "Notification title",
"notification_ios_badge": 1
}
}
### Data messages
FCM data messages are sent as an arbitrary k/v structure and by default are passed to the app for it to handle them.
**NOTE:** FCM data messages **cannot** be sent from the Firebase Console - they can only be sent via the FCM APIs.
**IMPORTANT:** Data messages can only be received while your app is running in the foreground.
If it's in the background or not running running, the app will not receive the data message.
#### Data message notifications
This plugin enables a data message to be displayed as a system notification.
To have the app display a notification when the data message arrives, you need to set the `notification_foreground` key in the `data` section.
You can then set a `notification_title` and `notification_body`, for example:
{
"name": "my_data",
"data" : {
"notification_foreground": "true",
"notification_body" : "Notification body",
"notification_title": "Notification title",
"foo" : "bar"
}
}
Additional platform-specific notification options can be set using the additional keys below (which are only relevant if the `notification_foreground` key is set).
Note: [foreground notification messages](#foreground-notifications) can also make use of these keys.
##### Android data message notifications
The following Android-specific keys are supported and should be placed inside the `data` section:
- `notification_android_icon` - name of a [custom notification icon](#android-custom-notification-icons) in the drawable resources
- if not specified, the plugin will use the default `notification_icon` if it exists; otherwise the default app icon will be displayed
- if a [large icon](#android-large-notification-icon) has been defined, it will also be displayed in the system notification.
- `notification_android_color` - the [color accent](#android-notification-color) to use for the small notification icon
- if not specified, the default color accent will be used
- `notification_android_channel_id` - ID of the [notification channel](#android-notification-channels) to use to display the notification
- Only applies to Android 8.0 and above
- If not specified, the [default notification channel](#default-android-channel-properties) will be used.
- You can override the default configuration for the default notification channel using [setDefaultChannel](#setdefaultchannel).
- You can create additional channels using [createChannel](#createchannel).
- `notification_android_priority` - Specifies the notification priority
- Possible values:
- `2` - Highest notification priority for your application's most important items that require the user's prompt attention or input.
- `1` - Higher notification priority for more important notifications or alerts.
- `0` - Default notification priority.
- `-1` - Lower notification priority for items that are less important.
- `-2` - Lowest notification priority. These items might not be shown to the user except under special circumstances, such as detailed notification logs.
- Defaults to `2` if not specified.
- `notification_android_visibility` - Specifies the notification visibility
- Possible values:
- `1` - Show this notification in its entirety on all lockscreens.
- `0` - Show this notification on all lockscreens, but conceal sensitive or private information on secure lockscreens.
- `-1` - Do not reveal any part of this notification on a secure lockscreen.
- Defaults to `1` if not specified.
The following keys only apply to Android 7 and below.
On Android 8 and above they will be ignored - the `notification_android_channel_id` property should be used to specify a [notification channel](#android-notification-channels) with equivalent settings.
- `notification_android_sound` - name of a sound resource to play as the [notification sound](#android-notification-sound)
- if not specified, no sound is played
- `default` plays the default device notification sound
- otherwise should be the name of an `.mp3` file in the `/res/raw` directory, e.g. `my_sound.mp3` => `"sounds": "my_sound"`
- `notification_android_lights` - color and pattern to use to blink the LED light
- if not defined, LED will not blink
- in the format `ARGB, time_on_ms, time_off_ms` where
- `ARGB` is an ARGB color definition e.g. `#ffff0000`
- `time_on_ms` is the time in milliseconds to turn the LED on for
- `time_off_ms` is the time in milliseconds to turn the LED off for
- e.g. `"lights": "#ffff0000, 250, 250"`
- `notification_android_vibrate` - pattern of vibrations to use when the message arrives
- if not specified, device will not vibrate
- an array of numbers specifying the time in milliseconds to vibrate
- e.g. `"vibrate": "500, 200, 500"`
Example data message with Android notification keys:
{
"name": "my_data_message",
"data" : {
"notification_foreground": "true",
"notification_body" : "Notification body",
"notification_title": "Notification title",
"notification_android_channel_id": "my_channel",
"notification_android_priority": "2",
"notification_android_visibility": "1",
"notification_android_color": "#ff0000",
"notification_android_icon": "coffee",
"notification_android_sound": "crystal",
"notification_android_vibrate": "500, 200, 500",
"notification_android_lights": "#ffff0000, 250, 250"
}
}
##### iOS data message notifications
## Google Tag Manager
Download your container-config json file from Tag Manager and add a resource-file node in your `config.xml`.
### Android
```
<platform name="android">
<resource-file src="GTM-XXXXXXX.json" target="assets/containers/GTM-XXXXXXX.json" />
...
```
### iOS
```
<platform name="ios">
<resource-file src="GTM-YYYYYYY.json" />
...
```
## API
The list of available methods for this plugin is described below.
### Notifications and data messages
The plugin is capable of receiving push notifications and FCM data messages.
See [Cloud messaging](#cloud-messaging) section for more.
#### getToken
Get the device token (id):
```
window.FirebasePlugin.getToken(function(token) {
// save this server-side and use it to push notifications to this device
console.log(token);
}, function(error) {
console.error(error);
});
```
Note that token will be null if it has not been established yet.
#### onTokenRefresh
Register for token changes:
```
window.FirebasePlugin.onTokenRefresh(function(token) {
// save this server-side and use it to push notifications to this device
console.log(token);
}, function(error) {
console.error(error);
});
```
This is the best way to get a valid token for the device as soon as the token is established
#### onMessageReceived
Registers a callback function to invoke when notification/data message is received by the app:
```
window.FirebasePlugin.onMessageReceived(function(message) {
console.log("Message type: " + message.messageType);
if(message.messageType === "notification"){
console.log("Notification message received in " + (message.tap ? "background" : "foreground"));
}
console.dir(notification);
}, function(error) {
console.error(error);
});
```
The `message` object passed to the callback function will contain the full platform-specific FCM message payload along with the following keys:
- `messageType=notification|data` - indicates if received message is a notification or data message
- `tap=true|false` - if `messageType=notification`, indicates if message was received while app was in the foreground (`tap=false`) or while the app was in the background and the app was launched by the user tapping the system notification (`tap=true`).
Notification message flow:
1. App is in foreground:
a. By default, when a notification message arrives the app receives the notification message payload in the `onMessageReceived` JavaScript callback without any system notification on the device itself.
b. If the `data` section contains the `notification_foreground` key, the plugin will display a system notification while in the foreground.
2. App is in background:
a. User receives the notification message as a system notification in the device notification bar
b. User taps the system notification which launches the app
b. User receives the notification message payload in the `onMessageReceived` JavaScript callback
Data message flow:
1. App is in foreground:
a. By default, when a data message arrives the app receives the data message payload in the `onMessageReceived` JavaScript callback without any system notification on the device itself.
b. If the `data` section contains the `notification_foreground` key, the plugin will display a system notification while in the foreground.
2. App is in background:
a. The app receives the data message in the `onMessageReceived` JavaScript callback while in the background
b. If the data message contains the [data message notification keys](#data-message-notifications), the plugin will display a system notification for the data message while in the background.
#### grantPermission
Grant permission to receive push notifications (will trigger prompt) and return `hasPermission: true`.
iOS only (Android will always return true).
```
window.FirebasePlugin.grantPermission(function(hasPermission){
console.log("Permission was " + (hasPermission ? "granted" : "denied"));
});
```
#### hasPermission
Check permission to receive push notifications and return `hasPermission: true`.
iOS only (Android will always return true).
```
window.FirebasePlugin.hasPermission(function(hasPermission){
console.log("Permission is " + (hasPermission ? "granted" : "denied"));
});
```
#### unregister
Unregister from firebase, used to stop receiving push notifications.
Call this when you logout user from your app.
```
window.FirebasePlugin.unregister();
```
#### setBadgeNumber
Set a number on the icon badge:
```
window.FirebasePlugin.setBadgeNumber(3);
```
Set 0 to clear the badge
```
window.FirebasePlugin.setBadgeNumber(0);
```
#### getBadgeNumber
Get icon badge number:
```
window.FirebasePlugin.getBadgeNumber(function(n) {
console.log(n);
});
```
#### clearAllNotifications
Clear all pending notifications from the drawer:
```
window.FirebasePlugin.clearAllNotifications();
```
#### subscribe
Subscribe to a topic.
Topic messaging allows you to send a message to multiple devices that have opted in to a particular topic.
```
window.FirebasePlugin.subscribe("latest_news");
```
#### unsubscribe
Unsubscribe from a topic.
This will stop you receiving messages for that topic
```
window.FirebasePlugin.unsubscribe("latest_news");
```
#### createChannel
Android 8+ only.
Creates a custom channel to be used by notification messages which have the channel property set in the message payload to the `id` of the created channel:
- For background (system) notifications: `android.notification.channel_id`
- For foreground/data notifications: `data.notification_android_channel_id`
For each channel you may set the sound to be played, the color of the phone LED (if supported by the device), whether to vibrate and set vibration pattern (if supported by the device), importance and visibility.
Channels should be created as soon as possible (on program start) so notifications can work as expected.
A default channel is created by the plugin at app startup; the properties of this can be overridden see [setDefaultChannel](#setdefaultchannel)
Calling on Android 7 or below or another platform will have no effect.
```
// Define custom channel - all keys are except 'id' are optional.
var channel = {
// channel ID - must be unique per app package
id: "my_channel_id",
// Channel name. Default: empty string
name: "Channel name",
//The sound to play once a push comes. Default value: 'default'
//Values allowed:
//'default' - plays the default notification sound
//'ringtone' - plays the currently set ringtone
//'false' - silent; don't play any sound
//filename - the filename of the sound file located in '/res/raw' without file extension (mysound.mp3 -> mysound)
sound: "mysound",
//Vibrate on new notification. Default value: true
//Possible values:
//Boolean - vibrate or not
//Array - vibration pattern - e.g. [500, 200, 500] - milliseconds vibrate, milliseconds pause, vibrate, pause, etc.
vibration: true,
// Whether to blink the LED
light: true,
//LED color in ARGB format - this example BLUE color. If set to -1, light color will be default. Default value: -1.
lightColor: "0xFF0000FF",
//Importance - integer from 0 to 4. Default value: 4
//0 - none - no sound, does not show in the shade
//1 - min - no sound, only shows in the shade, below the fold
//2 - low - no sound, shows in the shade, and potentially in the status bar
//3 - default - shows everywhere, makes noise, but does not visually intrude
//4 - high - shows everywhere, makes noise and peeks
importance: 4,
//Show badge over app icon when non handled pushes are present. Default value: true
badge: true,
//Show message on locked screen. Default value: 1
//Possible values (default 1):
//-1 - secret - Do not reveal any part of the notification on a secure lockscreen.
//0 - private - Show the notification on all lockscreens, but conceal sensitive or private information on secure lockscreens.
//1 - public - Show the notification in its entirety on all lockscreens.
visibility: 1
};
// Create the channel
window.FirebasePlugin.createChannel(options,
function(){
console.log('Channel created: ' + options.id);
},
function(error){
console.log('Create channel error: ' + error);
});
```
Example FCM v1 API notification message payload for invoking the above example channel:
```
{
"notification":
{
"title":"Notification title",
"body":"Notification body",
},
"android": {
"notification": {
"channel_id": "my_channel_id"
}
}
}
```
#### setDefaultChannel
Android 8+ only.
Overrides the properties for the default channel.
The default channel is used if no other channel exists or is specified in the notification.
Any options not specified will not be overridden.
Should be called as soon as possible (on app start) so default notifications will work as expected.
Calling on Android 7 or below or another platform will have no effect.
```
var options = {
id: "my_default_channel",
name: "My Default Name",
sound: "ringtone",
vibration: [500, 200, 500],
light: true,
lightColor: "0xFF0000FF",
importance: 4,
badge: false,
visibility: -1
};
window.FirebasePlugin.setDefaultChannel(options,
function(){
console.log('Channel created: ' + options.id);
},
function(error){
console.log('Create channel error: ' + error);
});
```
#### Default Android Channel Properties
The default channel is initialised at app startup with the following default settings:
```
{
id: "fcm_default_channel",
name: "Default",
sound: "default",
vibration: true,
light: true,
lightColor: -1,
importance: 4,
badge: true,
visibility: 1
}
```
#### deleteChannel
Android 8+ only.
Removes a previously defined channel.
Calling on Android 7 or below or another platform will have no effect.
```
window.FirebasePlugin.deleteChannel("my_channel_id",
function(){
console.log('Channel deleted');
},
function(error){
console.log('Delete channel error: ' + error);
});
```
#### listChannels
Android 8+ only.
Gets a list of all channels.
Calling on Android 7 or below or another platform will have no effect.
```
window.FirebasePlugin.listChannels(
function(channels){
if(typeof channels == "undefined")
return;
for(var i=0;i<channels.length;i++)
{
console.log("ID: " + channels[i].id + ", Name: " + channels[i].name);
}
},
function(error){
alert('List channels error: ' + error);
});
```
### Analytics
Firebase Analytics enables you to log events in order to track use and behaviour of your apps.
By default, Firebase does not store fine-grain analytics data - only a sample is taken and detailed event data is then discarded.
The Firebase Analytics console is designed to give you a coarse overview of analytics data.
If you want to analyse detailed, event-level analytics you should consider [exporting Firebase Analytics data to BigQuery](https://firebase.google.com/docs/projects/bigquery-export).
The easiest way to set this up is by [streaming Firebase Analytics data into BigQuery](https://cloud.google.com/bigquery/streaming-data-into-bigquery).
Note that until you set this up, all fine-grain event-level data is discarded by Fireba