cordova-plugin-firebasex-with-upstream-messaging
Advanced tools
Cordova plugin for Google Firebase
Brings push notifications, analytics, event tracking, crash reporting and more from Google Firebase to your Cordova project.
Supported platforms: Android and iOS
IMPORTANT: Before opening an issue against this plugin, please read Reporting issues.
This branch of the plugin is specifically intended for those building (directly or indirectly) via the Cordova CLI. It removes the Firebase Inapp Messaging and Google Tag Manager SDK components due to these causing CLI builds to fail (see #326).
To use it, install an npm release with the -cli suffix, e.g.:
cordova plugin add cordova-plugin-firebasex@9.0.1-cli
Or install it directly from this branch:
cordova plugin add https://github.com/dpa99c/cordova-plugin-firebasex#cli_build
If you wish to use either of these components, please use the master branch or install a major plugin release via the NPM registry and build using Xcode.
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.
Table of Contents
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
The following Cordova plugin variables are supported by the plugin. Note that these must be set at plugin installation time. If you wish to change plugin variables, you'll need to uninstall the plugin and reinstall it with the new variable values.
FIREBASE_ANALYTICS_COLLECTION_ENABLED - whether to automatically enable Firebase Analytics data collection on app startupFIREBASE_PERFORMANCE_COLLECTION_ENABLED - whether to automatically enable Firebase Performance data collection on app startupFIREBASE_CRASHLYTICS_COLLECTION_ENABLED - whether to automatically enable Firebase Crashlytics data collection on app startup
See Disable data collection on startup for more info.The following plugin variables are used to specify the Firebase SDK versions as Gradle dependencies on Android:
ANDROID_PLAY_SERVICES_TAGMANAGER_VERSION
ANDROID_PLAY_SERVICES_AUTH_VERSION
ANDROID_FIREBASE_ANALYTICS_VERSION
ANDROID_FIREBASE_MESSAGING_VERSION
ANDROID_FIREBASE_CONFIG_VERSION
ANDROID_FIREBASE_PERF_VERSION
ANDROID_FIREBASE_AUTH_VERSION
ANDROID_FIREBASE_FIRESTORE_VERSION
ANDROID_FIREBASE_CRASHLYTICS_VERSION
ANDROID_FIREBASE_CRASHLYTICS_NDK_VERSION
ANDROID_GSON_VERSION
ANDROID_FIREBASE_PERF_GRADLE_PLUGIN_VERSION
ANDROID_FIREBASE_PERFORMANCE_MONITORING
See Specifying Android library versions for more info.
ANDROID_ICON_ACCENT - sets the default accent color for system notifications. See Android Notification Color for more info.
ANDROID_FIREBASE_CONFIG_FILEPATH - sets a custom filepath to google-services.json file as a path relative to the project root
--variable ANDROID_FIREBASE_CONFIG_FILEPATH="resources/android/google-services.json"ANDROID_FIREBASE_PERFORMANCE_MONITORING - sets whether to add the Firebase Performance Monitoring Gradle plugin for Android to the build.
--variable ANDROID_FIREBASE_PERFORMANCE_MONITORING=truefalse if not specified.ANDROID_FIREBASE_PERF_GRADLE_PLUGIN_VERSION - overrides the default version of the Firebase Performance Monitoring Gradle plugin for Android
IOS_STRIP_DEBUG - prevents symbolification of all libraries included via Cocoapods. See Strip debug symbols for more info.
--variable IOS_STRIP_DEBUG=truefalse if not specified.SETUP_RECAPTCHA_VERIFICATION - automatically sets up reCAPTCHA verification for phone authentication on iOS. See verifyPhoneNumber for more info.
--variable IOS_STRIP_DEBUG=truefalse if not specified.IOS_SHOULD_ESTABLISH_DIRECT_CHANNEL - If true Firebase Messaging will automatically establish a socket-based, direct channel to the FCM server.
--variable IOS_SHOULD_ESTABLISH_DIRECT_CHANNEL=truefalse if not specified.shouldEstablishDirectChannelIOS_FIREBASE_CONFIG_FILEPATH - sets a custom filepath to GoogleService-Info.plist file as a path relative to the project root
--variable IOS_FIREBASE_CONFIG_FILEPATH="resources/ios/GoogleService-Info.plist"IOS_ENABLE_APPLE_SIGNIN - enables the Sign In with Apple capability in Xcode.
--variable IOS_ENABLE_APPLE_SIGNIN=true>= 9>= 9>= 6>= 4.1>= 10.0This plugin is a fork of cordova-plugin-firebase which has been reworked to fix issues and add new functionality. If you already have 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.
You should be aware of the following breaking changes compared with cordova-plugin-firebase:
cordova@9 (CLI)cordova-android@8 (Android platform)cordova-ios@5 (iOS platform)onNotificationOpen() renamed to onMessageReceived()
tap parameter is only set when user taps on a notification (not when a message is received from FCM)tap=foreground|background instead of tap=true|falsehasPermission() receives argument as a boolean (rather than an object with isEnabled key)
FirebasePlugin.hasPermission(function(hasPermission){ console.log("Permission is " + (hasPermission ? "granted" : "denied")); });Ionic Native provides a FirebaseX Typescript wrapper for using cordova-plugin-firebasex with Ionic v4, v5 and above.
Please see their documentation for usage.
First install the package.
ionic cordova plugin add cordova-plugin-firebasex
npm install @ionic-native/firebase-x
If you're using Angular, register it in your component/service's NgModule (for example, app.module.ts) as a provider.
import { FirebaseX } from "@ionic-native/firebase-x/ngx";
@NgModule({
//declarations, imports...
providers: [
FirebaseX,
//other providers...
]
})
Then you're good to go.
import { FirebaseX } from "@ionic-native/firebase-x/ngx";
//...
constructor(private firebase: FirebaseX)
this.firebase.getToken().then(token => console.log(`The token is ${token}`))
this.firebase.onMessageReceived().subscribe(data => console.log(`FCM message: ${data}`));
NOTE:
The above PR does not work for Ionic 3 so you (currently) can't use the Ionic Native Firebase Typescript wrapper with Ionic 3.
(i.e. import { Firebase } from "@ionic-native/firebase" will not work).
To use cordova-plugin-firebasex with Ionic 3, you'll need to call its Javascript API directly from your Typescript app code, for example:
(<any>window).FirebasePlugin.getToken(token => console.log(`token: ${token}`))
(<any>window).FirebasePlugin.onMessageReceived((message) => {
if (message.tap) { console.log(`Notification was tapped in the ${message.tap}`); }
})
If you want to make the onMessageReceived() JS API behave like the Ionic Native wrapper:
onNotificationOpen() {
return new Observable(observer => {
(window as any).FirebasePlugin.onMessageReceived((response) => {
observer.next(response);
});
});
}
...
this.onNotificationOpen().subscribe(data => console.log(`FCM message: ${data}`));
See the cordova-plugin-firebasex-ionic3-test example project for a demonstration of how to use the plugin with Ionic 3.
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.
This plugin depends on various components such as the Firebase SDK which are pulled in at build-time by Gradle on Android.
By default this plugin pins specific versions of these in its plugin.xml where you can find the currently pinned versions as <preference>'s, for example:
<preference name="ANDROID_FIREBASE_ANALYTICS_VERSION" default="17.0.0" />
The Android 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_ANALYTICS_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_ANALYTICS_VERSION" value="17.0.0" />
</plugin>
The following plugin variables are used to specify the following Gradle dependency versions on Android:
ANDROID_PLAY_SERVICES_TAGMANAGER_VERSION => com.google.android.gms:play-services-tagmanagerANDROID_PLAY_SERVICES_AUTH_VERSION => com.google.android.gms:play-services-authANDROID_FIREBASE_ANALYTICS_VERSION => com.google.firebase:firebase-analyticsANDROID_FIREBASE_MESSAGING_VERSION => com.google.firebase:firebase-messagingANDROID_FIREBASE_CONFIG_VERSION => com.google.firebase:firebase-configANDROID_FIREBASE_PERF_VERSION => com.google.firebase:firebase-perfANDROID_FIREBASE_AUTH_VERSION => com.google.firebase:firebase-authANDROID_FIREBASE_FIRESTORE_VERSION => com.google.firebase:firebase-firestoreANDROID_FIREBASE_CRASHLYTICS_VERSION => com.google.firebase:firebase-crashlyticsANDROID_FIREBASE_CRASHLYTICS_NDK_VERSION => com.google.firebase:firebase-crashlytics-ndkANDROID_GSON_VERSION => com.google.code.gson:gsonFor example:
cordova plugin add cordova-plugin-firebasex \
--variable ANDROID_PLAY_SERVICES_TAGMANAGER_VERSION=17.0.0 \
--variable ANDROID_PLAY_SERVICES_AUTH_VERSION=17.0.0 \
--variable ANDROID_FIREBASE_ANALYTICS_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_FIREBASE_CRASHLYTICS_VERSION=17.0.1 \
--variable ANDROID_FIREBASE_CRASHLYTICS_NDK_VERSION=17.0.1 \
This plugin has been migrated to use AndroidX (Jetpack) which is the successor to the Android Support Library. This is because the major release of the Firebase and Play Services libraries on 17 June 2019 were migrated to AndroidX.
The cordova-android@9 platform adds implicit support for AndroidX so (if you haven't already done so) you should update to this platform version:
cordova platform rm android && cordova platform add android@latest
and enable AndroidX by setting the following preference in your config.xml:
<preference name="AndroidXEnabled" value="true" />
If you are unable to update from cordova-android@8, you can add cordova-plugin-androidx to your project which enables AndroidX in the Android platform project:
cordova plugin add cordova-plugin-androidx
If your project includes any plugins which are dependent on the legacy Android Support Library (to which AndroidX is the successor), you should add cordova-plugin-androidx-adapter to your project which will dynamically migrate any plugin code from the Android Support Library to AndroidX equivalents:
cordova plugin add cordova-plugin-androidx-adapter
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 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 to align these.
Please ensure you have the latest Xcode release version installed to build your app - direct download links can be found here.
This plugin depends on various components such as the Firebase SDK which are pulled in at build-time by Cocoapods on iOS.
This plugin pins specific versions of these in its plugin.xml where you can find the currently pinned iOS versions in the <pod>'s, for example:
<pod name="Firebase/Core" spec="6.3.0"/>
It is currently not possible to override these at plugin installation time because cordova@9/cordova-ios@5 does not support the use of plugin variables in the <pod>'s spec attribute.
Therefore if you need to change the specified versions, you'll currently need to do this by forking the plugin and editing the plugin.xml to change the specified spec values.
This plugin relies on cordova@9/cordova-ios@5 support for the CocoaPods dependency manager in order to satisfy the iOS Firebase SDK library dependencies.
Therefore please make sure you have cocoapods@>=1.9 installed in your iOS build environment - setup instructions can be found here.
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:
sudo gem install cocoapods-dependencies
cd platforms/ios/
pod dependencies
If you receive a build error such as this:
None of your spec sources contain a spec satisfying the dependencies: `Firebase/Analytics (~> 6.1.0), Firebase/Analytics (= 6.1.0, ~> 6.1.0)`.
Make sure your local Cocoapods repo is up-to-date by running pod repo update then run pod install in /your_project/platforms/ios/.
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) 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 for more information):
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.
If you are building (directly or indirectly) via the Cordova CLI and a build failures on iOS such as the one below:
error: Resource "/Build/Products/Debug-iphonesimulator/FirebaseInAppMessaging/InAppMessagingDisplayResources.bundle" not found. Run 'pod install' to update the copy resources script.
This is likely due to an issue with Cordova CLI builds for iOS when including certain pods into the build (see #326):
Note that building from Xcode works fine, so if you are able then do this.
Otherwise (e.g. if building via a CI) then you'll need to switch to using the cli_build branch of this plugin:
cordova plugin rm cordova-plugin-firebasex && cordova plugin add cordova-plugin-firebasex@latest-cli
This removes the Firebase Inapp Messaging and Google Tag Manager SDK components that are causing the build issues.
The cli_build branch is kept in sync with master but without the above components.
You can validate your CLI build environment using this publicly-available GoogleService-Info.plist:
cordova create test com.canary.CanaryApparel && cd test
curl https://github.coventry.ac.uk/raw/301CEM-1920OCTJAN/301CEM-6957713/master/CanaryApparel/GoogleService-Info.plist -o GoogleService-Info.plist
cordova plugin add cordova-plugin-firebasex@latest-cli
cordova platform add ios
cordova build ios --emulator
#build succeeds
Following the installation steps above, modify the package.json file to pin the cli variant of this package by removing the ^ or ~ prefix from the package declaration. Failure to do this will result in build issues the next time the cordova prepare steps are performed as the non-cli version of the package will replace the cli variant.
"dependencies": {
"cordova-android": "~8.1.0",
"cordova-ios": "^6.1.0",
"cordova-plugin-androidx": "^2.0.0",
"cordova-plugin-androidx-adapter": "^1.1.1",
"cordova-plugin-firebasex": "^10.1.2-cli" --> Change to "10.1.2-cli"
},
There's a handy installation and setup guide on medium.com.
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 for details on how to download the files.
- My Project/
platforms/
plugins/
www/
config.xml
google-services.json <--
GoogleService-Info.plist <--
...
Or you can set custom location for your platform configuration files using plugin variables in your config.xml:
<plugin name="cordova-plugin-firebasex">
<variable name="ANDROID_FIREBASE_CONFIG_FILEPATH" value="resources/android/google-services.json" />
<variable name="IOS_FIREBASE_CONFIG_FILEPATH" value="resources/ios/GoogleService-Info.plist" />
</plugin>
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.
By default, analytics, performance and Crashlytics data will begin being collected as soon as the app starts up. However, for data protection or privacy reasons, you may wish to disable data collection until such time as the user has granted their permission.
To do this, set the following plugin variables to false at plugin install time:
FIREBASE_ANALYTICS_COLLECTION_ENABLED
FIREBASE_PERFORMANCE_COLLECTION_ENABLED
FIREBASE_CRASHLYTICS_COLLECTION_ENABLED
cordova plugin add cordova-plugin-firebasex
--variable FIREBASE_ANALYTICS_COLLECTION_ENABLED=false
--variable FIREBASE_PERFORMANCE_COLLECTION_ENABLED=false
--variable FIREBASE_CRASHLYTICS_COLLECTION_ENABLED=false
This will disable data collection (on both Android & iOS) until you call setAnalyticsCollectionEnabled, setPerformanceCollectionEnabled and setCrashlyticsCollectionEnabled:
FirebasePlugin.setAnalyticsCollectionEnabled(true);
FirebasePlugin.setPerformanceCollectionEnabled(true);
FirebasePlugin.setCrashlyticsCollectionEnabled(true);
Notes:
setXCollectionEnabled() will have no effect if the corresponding FIREBASE_X_COLLECTION_ENABLED variable is set to true.setXCollectionEnabled(true|false) will enable/disable data collection during the current app session and across subsequent app sessions until such time as the same method is called again with a different value.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.
Before reporting any issues, please (if possible) test against the example project to rule out causes external to this plugin.
IMPORTANT: Please read the following carefully. Failure to follow the issue template guidelines below will result in the issue being immediately closed.
Before opening a bug issue, please do the following:
cordova-plugin-firebasex please make sure you have read the Migrating from cordova-plugin-firebase section.--verbose flag to CLI build commandscordova build ios --verboseBefore opening a feature request issue, please do the following:
There are 2 distinct types of messages that can be sent by Firebase Cloud Messaging (FCM):
Note: only notification messages can be sent via the Firebase Console - data messages must be sent via the FCM APIs.
If the notification message arrives while the app is in the background/not running, it will be displayed as a system notification.
By default, no callback is made to the plugin when the message arrives while the app is not in the foreground, since the display of the notification is entirely handled by the operating system. However, there are platform-specific circumstances where a callback can be made when the message arrives and the app is in the background that don't require user interaction to receive the message payload - see Android background notifications and iOS background notifications for details.
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 callback.
When the onMessageReceived is called in response to a user tapping a system notification while the app is in the background/not running, it will be passed the property tap: "background".
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 callback for the plugin to handle (tap will not be set).
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",
}
}
When the onMessageReceived is called in response to a user tapping a system notification while the app is in the foreground, it will be passed the property tap: "foreground".
You can set additional properties of the foreground notification using the same key names as for Data Message Notifications.
Notifications on Android can be customised to specify the sound, icon, LED colour, etc. that's displayed when the notification arrives.
If the notification message arrives while the app is in the background/not running, it will be displayed as a system notification.
If a notification message arrives while the app is in the background but is still running (i.e. has not been task-killed) and the device is not in power-saving mode, the onMessageReceived callback will be invoked without the tap property, indicating the message was received without user interaction.
If the user then taps the system notification, the app will be brought to the foreground and onMessageReceived will be invoked again, this time with tap: "background" indicating that the user tapped the system notification while the app was in the background.
In addition to the title and body of the notification message, Android system notifications support specification of the following notification settings:
Note: on tapping a background notification, if your app is not running, only the data section of the notification message payload will be delivered to onMessageReceived.
i.e. the notification title, body, etc. will not. Therefore if you need the properties of the notification message itself (e.g. title & body) to be delivered to onMessageReceived, you must duplicate these in the data section, e.g.:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"data": {
"notification_body": "Notification body",
"notification_title": "Notification title"
}
}
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.
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.
First you need to create a custom channel with the desired settings, for example:
var channel = {
id: "my_channel_id",
sound: "mysound",
vibration: true,
light: true,
lightColor: parseInt("FF0000FF", 16).toString(),
importance: 4,
badge: true,
visibility: 1
};
FirebasePlugin.createChannel(channel,
function(){
console.log('Channel created: ' + channel.id);
},
function(error){
console.log('Create channel error: ' + error);
});
Then reference it from your message payload:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"android": {
"notification": {
"channel_id": "my_channel_id"
}
}
}
By default the plugin will use the default app icon for notification messages.
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 create the images is using the Image Asset Studio in Android Studio or using the Android Asset Studio webapp.
The icons should be monochrome transparent PNGs with the following sizes:
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, where src specifies the relative path to the images files within your Cordova project directory.
For example, copy thedrawable-DPI image directories to <projectroot>/res/android/ and add the following to your config.xml:
<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="/manifest/application">
<meta-data android:name="com.google.firebase.messaging.default_notification_icon" android:resource="@drawable/notification_icon" />
</config-file>
</platform>
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 or 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>
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, for example:
{
"name": "my_data",
"data" : {
"notification_foreground": "true",
"notification_body" : "Notification body",
"notification_title": "Notification title",
"notification_android_icon": "my_icon",
}
}
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 which the plugin sets by default to #FF00FFFF (cyan).
Note: On Android 7 and above, the accent color can only be set for the notification displayed in the system tray area - the icon in the statusbar is always white.
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"
}
}
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>
To ensure your custom sounds works on all versions of Android, be sure to include both the channel name and sound name in your message payload (see below for details), for example:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"android": {
"notification": {
"channel_id": "my_channel_id",
"sound": "my_sound"
}
}
}
On Android 8.0 and above, the notification sound is specified by which Android notification channel is referenced in the notification message payload. First create a channel that references your sound, for example:
var channel = {
id: "my_channel_id",
sound: "my_sound"
};
FirebasePlugin.createChannel(channel,
function(){
console.log('Channel created: ' + channel.id);
},
function(error){
console.log('Create channel error: ' + error);
});
Then reference that channel in your message payload:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"android": {
"notification": {
"channel_id": "my_channel_id"
}
}
}
On Android 7 and below, you need to specify the sound file name in the android.notification section of the message payload.
For example:
{
"name": "my_notification",
"notification": {
"body": "Notification body",
"title": "Notification title"
},
"android": {
"notification": {
"sound": "my_sound"
}
}
}
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": "my_sound"
}
}
"sound": "default".sound key from the message.The type of payload data in an FCM message influences how the message will be delivered to the app dependent on its run state, as outlined in this Firebase documentation.
| App run state | Notification payload | Data payload | Notification+Data payload |
|---|---|---|---|
| Foreground | onMessageReceived | onMessageReceived | onMessageReceived |
| Background | System tray[1] | onMessageReceived | Notification payload: System tray[1] Data payload: onMessageReceived via extras of New Intent[2] |
| Not running | System tray[1] | Never received[3] | Notification payload: System tray[1] Data payload: onMessageReceived via extras of Launch Intent[2] |
1: If user taps the system notification, its payload is delivered to onMessageReceived
2: The data payload is only delivered as an extras Bundle Intent if the user taps the system notification. Otherwise it will not be delivered as outlined in this Firebase documentation.
3: If the app is not running/has been task-killed when the data message arrives, it will never be received by the app.
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,
"content-available": 1
}
}
}
}
If the app is in the background but is still running (i.e. has not been task-killed) and the device is not in power-saving mode, the onMessageReceived callback can be invoked when the message arrives without requiring user interaction (i.e. tapping the system notification).
To do this you must specify "content-available": 1 in the apns.payload.aps section of the message payload - see the Apple documentation for more information.
When the message arrives, the onMessageReceived callback will be invoked without the tap property, indicating the message was received without user interaction.
If the user then taps the system notification, the app will be brought to the foreground and onMessageReceived will be invoked again, this time with tap: "background" indicating that the user tapped the system notification while the app was in the background.
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 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"
}
}
}
}
"sound": "default".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"
}
}
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
}
}
Actionable notifications are supported on iOS:
To use them in your app you must do the following:
pn-actions.json file to your Cordova project which defines categories and actions, for example: {
"PushNotificationActions": [
{
"category": "news",
"actions": [
{
"id": "read", "title": "Read", "foreground": true
},
{
"id": "skip", "title": "Skip"
},
{
"id": "delete", "title": "Delete", "destructive": true
}
]
}
]
}
Note the foreground and destructive options correspond to the equivalent UNNotificationActionOptions.
config.xml: <platform name="ios">
...
<resource-file src="relative/path/to/pn-actions.json" />
</platform>
{
"notification": {
"title": "iOS Actionable Notification",
"body": "With custom buttons"
},
"apns": {
"payload": {
"aps": {
"category": "news"
}
}
}
}
When the notification arrives, if the user presses an action button the onMessageReceived() function is invoked with the notification message payload, including the corresponding action ID.
For example:
{
"action": "read",
"google.c.a.e": "1",
"notification_foreground": "true",
"aps": {
"alert": {
"title": "iOS Actionable Notification",
"body": "With custom buttons"
},
"category": "news"
},
"gcm.message_id": "1597240847657854",
"tap": "background",
"messageType": "notification"
}
So you can obtain the category with message.aps.category and the action with message.action and handle this appropriately in your app code.
Notes:
onMessageReceived() will be invoked, enabling your app code to handle the user's action selection silently in the background.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.
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 can also make use of these keys.
On Android:
onMessageReceived() Javascript handler in the Webview.onMessageReceived() Javascript handler when the app is next launched.The following Android-specific keys are supported and should be placed inside the data section:
notification_android_icon - name of a custom notification icon in the drawable resources
notification_icon if it exists; otherwise the default app icon will be displayednotification_android_color - the color accent to use for the small notification icon
notification_android_channel_id - ID of the notification channel to use to display the notification
notification_android_priority - Specifies the notification priority
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.2 if not specified.notification_android_visibility - Specifies the notification visibility
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.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 with equivalent settings.
notification_android_sound - name of a sound resource to play as the notification sound
default plays the default device notification sound.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
ARGB, time_on_ms, time_off_ms where
ARGB is an ARGB color definition e.g. #ffff0000time_on_ms is the time in milliseconds to turn the LED on fortime_off_ms is the time in milliseconds to turn the LED off for"lights": "#ffff0000, 250, 250"notification_android_vibrate - pattern of vibrations to use when the message arrives
"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": "my_sound",
"notification_android_vibrate": "500, 200, 500",
"notification_android_lights": "#ffff0000, 250, 250"
}
}
On iOS:
onMessageReceived() Javascript handler in the Webview.The following iOS-specific keys are supported and should be placed inside the data section:
notification_ios_sound - Sound to play when the notification is displayed
"sound": "my_sound.caf" - see iOS notification sound for more info."sound": "default".sound key from the message.notification_ios_badge - Badge number to display on app icon on home screen.For example:
{
"name": "my_data",
"data" : {
"notification_foreground": "true",
"notification_body" : "Notification body",
"notification_title": "Notification title",
"notification_ios_sound": "my_sound.caf",
"notification_ios_badge": 1
}
}
In some cases you may want to handle certain incoming FCM messages differently rather than with the default behaviour of this plugin. Therefore this plugin provides a mechanism by which you can implement your own custom FCM message handling for specific FCM messages which bypasses handling of those messages by this plugin. To do this requires you to write native handlers for Android & iOS which hook into the native code of this plugin.
You'll need to add a native class which extends the FirebasePluginMessageReceiver abstract class and implements the onMessageReceived() and sendMessage() abstract methods.
You'll need to add a native class which extends the FirebasePluginMessageReceiver abstract class and implements the sendNotification() abstract method.
The example project contains an example plugin which implements a custom receiver class for both platforms. You can test this by building and running the example project app, and sending the notification_custom_receiver and data_custom_receiver test messages using the built-in FCM client.
The Firebase Inapp Messaging SDK component has been removed from this cli_build branch of the plugin due to the iOS component causing CLI builds to fail (see #326). If you wish to use Firebase Inapp Messaging, please use the master branch or install a plugin release via the NPM registry and build using Xcode.
The Google Tag Manager component has been removed from this cli_build branch of the plugin due to the iOS component causing CLI builds to fail (see #326). If you wish to use Google Tag Manager, please use the master branch or install a plugin release via the NPM registry and build using Xcode.
The Firebase Performance Monitoring SDK enables you to measure, monitor and analyze the performance of your app in the Firebase console. It enables you to measure metrics such as app startup, screen rendering and network requests.
ANDROID_FIREBASE_PERFORMANCE_MONITORING plugin variable flag at plugin install time:
--variable ANDROID_FIREBASE_PERFORMANCE_MONITORING=trueThe list of available methods for this plugin is described below.
The plugin is capable of receiving push notifications and FCM data messages.
See Cloud messaging section for more.
Get the current FCM token. Null if the token has not been allocated yet by the Firebase SDK.
Parameters:
FirebasePlugin.getToken(function(fcmToken) {
console.log(fcmToken);
}, function(error) {
console.error(error);
});
Note that token will be null if it has not been established yet.
Get the app instance ID (an constant ID which persists as long as the app is not uninstalled/reinstalled). Null if the ID has not been allocated yet by the Firebase SDK.
Parameters:
FirebasePlugin.getId(function(appInstanceId) {
console.log(appInstanceId);
}, function(error) {
console.error(error);
});
Note that token will be null if it has not been established yet.
Registers a handler to call when the FCM token changes.
This is the best way to get the token as soon as it has been allocated.
This will be called on the first run after app install when a token is first allocated.
It may also be called again under other circumstances, e.g. if unregister() is called or Firebase allocates a new token for other reasons.
You can use this callback to return the token to you server to keep the FCM token associated with a given user up-to-date.
Parameters:
FirebasePlugin.onTokenRefresh(function(fcmToken) {
console.log(fcmToken);
}, function(error) {
console.error(error);
});
iOS only. Get the APNS token allocated for this app install. Note that token will be null if it has not been allocated yet.
Parameters:
FirebasePlugin.getAPNSToken(function(apnsToken) {
console.log(apnsToken);
}, function(error) {
console.error(error);
});
iOS only. Registers a handler to call when the APNS token is allocated. This will be called once when remote notifications permission has been granted by the user at runtime.
Parameters:
FirebasePlugin.onApnsTokenReceived(function(apnsToken) {
console.log(apnsToken);
}, function(error) {
console.error(error);
});
Registers a callback function to invoke when:
Parameters:
FirebasePlugin.onMessageReceived(function(message) {
console.log("Message type: " + message.messageType);
if(message.messageType === "notification"){
console.log("Notification message received");
if(message.tap){
console.log("Tapped in " + message.tap);
}
}
console.dir(message);
}, function(error) {
console.error(error);
});
The message object passed to the callback function will contain the platform-specific FCM message payload along with the following keys:
messageType=notification|data - indicates if received message is a notification or data messagetap=foreground|background - set if the call to onMessageReceived() was initiated by user tapping on a system notification.
Notification message flow:
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.onMessageReceived JavaScript callbackData message flow:
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.onMessageReceived JavaScript callback while in the background
b. If the data message contains the data message notification keys, the plugin will display a system notification for the data message while in the background.Grant permission to receive push notifications (will trigger prompt) and return hasPermission: true.
iOS only (Android will always return true).
Parameters:
FirebasePlugin.grantPermission(function(hasPermission){
console.log("Permission was " + (hasPermission ? "granted" : "denied"));
});
Check permission to receive push notifications and return the result to a callback function as boolean. On iOS, returns true is runtime permission for remote notifications is granted and enabled in Settings. On Android, returns true if remote notifications are enabled.
Parameters:
FirebasePlugin.hasPermission(function(hasPermission){
console.log("Permission is " + (hasPermission ? "granted" : "denied"));
});
Unregisters from Firebase by deleting the current device token.
Use this to stop receiving push notifications associated with the current token.
e.g. call this when you logout user from your app.
By default, a new token will be generated as soon as the old one is removed.
To prevent a new token being generated, by sure to disable autoinit using setAutoInitEnabled() before calling unregister().
Parameters: None
FirebasePlugin.unregister();
Indicates whether autoinit is currently enabled. If so, new FCM tokens will be automatically generated.
Parameters:
FirebasePlugin.isAutoInitEnabled(function(enabled){
console.log("Auto init is " + (enabled ? "enabled" : "disabled"));
});
Sets whether to autoinit new FCM tokens.
By default, a new token will be generated as soon as the old one is removed.
To prevent a new token being generated, by sure to disable autoinit using setAutoInitEnabled() before calling unregister().
Parameters:
FirebasePlugin.setAutoInitEnabled(false, function(){
console.log("Auto init has been disabled ");
FirebasePlugin.unregister();
});
iOS only. Set a number on the icon badge:
Parameters:
FirebasePlugin.setBadgeNumber(3);
Set 0 to clear the badge
FirebasePlugin.setBadgeNumber(0);
Note: this function is no longer available on Android (see #124)
iOS only. Get icon badge number:
Parameters:
FirebasePlugin.getBadgeNumber(function(n) {
console.log(n);
});
Note: this function is no longer available on Android (see #124)
Clear all pending notifications from the drawer:
Parameters: None
FirebasePlugin.clearAllNotifications();
Subscribe to a topic.
Topic messaging allows you to send a message to multiple devices that have opted in to a particular topic.
Parameters:
FirebasePlugin.subscribe("latest_news", function(){
console.log("Subscribed to topic");
}, function(error){
console.error("Error subscribing to topic: " + error);
});
Unsubscribe from a topic.
This will stop you receiving messages for that topic
Parameters:
FirebasePlugin.unsubscribe("latest_news", function(){
console.log("Unsubscribed from topic");
}, function(error){
console.error("Error unsubscribing from topic: " + error);
});
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:
android.notification.channel_iddata.notification_android_channel_idFor 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
Calling on Android 7 or below or another platform will have no effect.
Parameters:
// 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 description. Default: empty string
description: "Channel description",
// 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: parseInt("FF0000FF", 16).toString(),
//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
FirebasePlugin.createChannel(channel,
function(){
console.log('Channel created: ' + channel.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"
}
}
}
If your Android app plays multiple sounds or effects, it's a good idea to create a channel for each likely combination. This is because once a channel is created you cannot override sounds/effects. IE, expanding on the createChannel example:
let soundList = ["train","woop","clock","radar","sonar"];
for (let key of soundList) {
let name = "yourchannelprefix_" + key;
channel.id = name;
channel.sound = key;
channel.name = "Your description " + key;
// Create the channel
window.FirebasePlugin.createChannel(channel,
function(){
console.log('Notification Channel created: ' + channel.id + " " + JSON.stringify(channel));
},
function(error){
console.log('Create notification channel error: ' + error);
});
}
Note, if you just have one sound / effect combination that the user can customise, just use setDefaultChannel when any changes are made.
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.
Parameters:
var channel = {
id: "my_default_channel",
name: "My Default Name",
description: "My Default Description",
sound: "ringtone",
vibration: [500, 200, 500],
light: true,
lightColor: parseInt("FF0000FF", 16).toString(),
importance: 4,
badge: false,
visibility: -1
};
FirebasePlugin.setDefaultChannel(channel,
function(){
console.log('Default channel set');
},
function(error){
console.log('Set default channel error: ' + error);
});
The default channel is initialised at app startup with the following default settings:
{
id: "fcm_default_channel",
name: "Default",
description: "",
sound: "default",
vibration: true,
light: true,
lightColor: -1,
importance: 4,
badge: true,
visibility: 1
}
Android 8+ only. Removes a previously defined channel. Calling on Android 7 or below or another platform will have no effect.
Parameters:
FirebasePlugin.deleteChannel("my_channel_id",
function(){
console.log('Channel deleted');
},
function(error){
console.log('Delete channel error: ' + error);
});
Android 8+ only. Gets a list of all channels. Calling on Android 7 or below or another platform will have no effect.
Parameters:
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);
});
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. The easiest way to set this up is by streaming Firebase Analytics data into BigQuery. Note that until you set this up, all fine-grain event-level data is discarded by Firebase.
Manually enable/disable analytics data collection, e.g. if disabled on app startup.
Parameters:
FirebasePlugin.setAnalyticsCollectionEnabled(true); // Enables analytics data collection
FirebasePlugin.setAnalyticsCollectionEnabled(false); // Disables analytics data collection
Indicates whether analytics data collection is enabled.
Notes:
true.Parameters:
FirebasePlugin.isAnalyticsCollectionEnabled(function(enabled){
console.log("Analytics data collection is "+(enabled ? "enabled" : "disabled"));
}, function(error){
console.error("Error getting Analytics data collection setting: "+error);
});
Log an event using Analytics:
Parameters:
FirebasePlugin.logEvent("select_content", {content_type: "page_view", item_id: "home"});
Set the name of the current screen in Analytics:
Parameters:
FirebasePlugin.setScreenName("Home");
Set a user id for use in Analytics:
Parameters:
FirebasePlugin.setUserId("user_id");
Set a user property for use in Analytics:
Parameters:
FirebasePlugin.setUserProperty("name", "value");
By default this plugin will ensure fatal native crashes in your apps are reported to Firebase via the Firebase (not Fabric) Crashlytics SDK.
Manually enable/disable Crashlytics data collection, e.g. if disabled on app startup.
Parameters:
var shouldSetEnabled = true;
FirebasePlugin.setCrashlyticsCollectionEnabled(shouldSetEnabled, function(){
console.log("Crashlytics data collection is enabled");
}, function(error){
console.error("Crashlytics data collection couldn't be enabled: "+error);
});
Checks whether the app crashed on its previous run.
Parameters:
FirebasePlugin.didCrashOnPreviousExecution(function(didCrashOnPreviousExecution){
console.log(`Did crash on previous execution: ${didCrashOnPreviousExecution}`));
}, function(error){
console.error(`Error getting Crashlytics did crash on previous execution: ${error}`);
});
Indicates whether Crashlytics collection setting is currently enabled.
Parameters:
FirebasePlugin.isCrashlyticsCollectionEnabled(function(enabled){
console.log("Crashlytics data collection is "+(enabled ? "enabled" : "disabled"));
}, function(error){
console.error("Error getting Crashlytics data collection setting: "+error);
});
Set Crashlytics user identifier.
To diagnose an issue, it’s often helpful to know which of your users experienced a given crash. Crashlytics includes a way to anonymously identify users in your crash reports. To add user IDs to your reports, assign each user a unique identifier in the form of an ID number, token, or hashed value.
See the Firebase docs for more.
Parameters:
FirebasePlugin.setCrashlyticsUserId("user_id");
Simulates (causes) a fatal native crash which causes a crash event to be sent to Crashlytics (useful for testing).
See the Firebase documentation regarding crash testing.
Crashes will appear under Event type = "Crashes" in the Crashlytics console.
Parameters: None
FirebasePlugin.sendCrash();
Records a custom key and value to be associated with subsequent fatal and non-fatal reports.
Multiple calls to this method with the same key will update the value for that key.
The value of any key at the time of a fatal or non-fatal event will be associated with that event.
Keys and associated values are visible in the session view on the Firebase Crashlytics console.
A maximum of 64 key/value pairs can be written, and new keys added beyond that limit will be ignored. Keys or values that exceed 1024 characters will be truncated.
Parameters:
FirebasePlugin.setCrashlyticsCustomKey('number', 3.5, function(){
console.log("set custom key: number, with value: 3.5");
},function(error){
console.error("Failed to set-custom key", error);
});
FirebasePlugin.setCrashlyticsCustomKey('bool', true);
FirebasePlugin.setCrashlyticsCustomKey('string', 'Ipsum lorem');
// Following is just used to trigger report for Firebase
FirebasePlugin.logMessage("about to send a crash for testing!");
FirebasePlugin.sendCrash();
Sends a crash-related log message that will appear in the Logs section of the next native crash event.
Note: if you don't then crash, the message won't be sent!
Also logs the message to the native device console.
Parameters:
FirebasePlugin.logMessage("about to send a crash for testing!");
FirebasePlugin.sendCrash();
Sends a non-fatal error event to Crashlytics. In a Cordova app, you may use this to log unhandled Javascript exceptions, for example.
The event will appear under Event type = "Non-fatals" in the Crashlytics console.
The error message will appear in the Logs section of the non-fatal error event.
Also logs the error message to the native device console.
Parameters:
// Send an unhandled JS exception
var appRootURL = window.location.href.replace("index.html",'');
window.onerror = function(errorMsg, url, line, col, error) {
var logMessage = errorMsg;
var stackTrace = null;
var sendError = function(){
FirebasePlugin.logError(logMessage, stackTrace, function(){
console.log("Sent JS exception");
},function(error){
console.error("Failed to send JS exception", error);
});
};
logMessage += ': url='+url.replace(appRootURL, '')+'; line='+line+'; col='+col;
if(typeof error === 'object'){
StackTrace.fromError(error).then(function(trace){
stackTrace = trace;
sendError()
});
}else{
sendError();
}
};
// Send a non-fatal error
FirebasePlugin.logError("A non-fatal error", function(){
console.log("Sent non-fatal error");
},function(error){
console.error("Failed to send non-fatal error", error);
});
An example of how the error entry will appear in the Crashlytics console:
Android
iOS
Checks if there is a current Firebase user signed into the app.
Parameters:
FirebasePlugin.isUserSignedIn(function(isSignedIn) {
console.log("User "+(isSignedIn ? "is" : "is not") + " signed in");
}, function(error) {
console.error("Failed to check if user is signed in: " + error);
});
Signs current Firebase user out of the app.
Parameters:
FirebasePlugin.signOutUser(function() {
console.log("User signed out");
}, function(error) {
console.error("Failed to sign out user: " + error);
});
Returns details of the currently logged in user from local Firebase SDK. Note that some user properties will be empty is they are not defined in Firebase for the current user.
Parameters:
FirebasePlugin.getCurrentUser(function(user) {
console.log("Name: "+user.name);
console.log("Email: "+user.email);
console.log("Is email verified?: "+user.emailIsVerified);
console.log("Phone number: "+user.phoneNumber);
console.log("Photo URL: "+user.photoUrl);
console.log("UID: "+user.uid);
console.log("Provider ID: "+user.providerId);
console.log("ID token: "+user.idToken);
}, function(error) {
console.error("Failed to get current user data: " + error);
});
Loads details of the currently logged in user from remote Firebase server.
This differs from getCurrentUser() which loads the locally cached details which may be stale.
For example, if you want to check if a user has verified their email address, this method will guarantee the reported verified state is up-to-date.
Parameters:
FirebasePlugin.reloadCurrentUser(function(user) {
console.log("Name: "+user.name);
console.log("Email: "+user.email);
console.log("Is email verified?: "+user.emailIsVerified);
console.log("Phone number: "+user.phoneNumber);
console.log("Photo URL: "+user.photoUrl);
console.log("UID: "+user.uid);
console.log("Provider ID: "+user.providerId);
console.log("ID token: "+user.idToken);
}, function(error) {
console.error("Failed to reload current user data: " + error);
});
Updates the display name and/or photo URL of the current Firebase user signed into the app.
Parameters:
FirebasePlugin.updateUserProfile({
name: "Homer Simpson",
photoUri: "http://homer.simpson.com/photo.png"
},function() {
console.log("User profile successfully updated");
}, function(error) {
console.error("Failed to update user profile: " + error);
});
Updates/sets the email address of the current Firebase user signed into the app.
Parameters:
FirebasePlugin.updateUserEmail("user@somewhere.com",function() {
console.log("User email successfully updated");
}, function(error) {
console.error("Failed to update user email: " + error);
});
Sends a verification email to the currently configured email address of the current Firebase user signed into the app. When the user opens the contained link, their email address will have been verified.
Parameters:
FirebasePlugin.sendUserEmailVerification(function() {
console.log("User verification email successfully sent");
}, function(error) {
console.error("Failed to send user verification email: " + error);
});
Updates/sets the account password for the current Firebase user signed into the app.
Parameters:
FirebasePlugin.updateUserPassword("mypassword",function() {
console.log("User password successfully updated");
}, function(error) {
console.error("Failed to update user password: " + error);
});
Sends a password reset email to the specified user email address. Note: doesn't require the Firebase user to be signed in to the app.
Parameters:
FirebasePlugin.sendUserPasswordResetEmail("user@somewhere.com",function() {
console.log("User password reset email sent successfully");
}, function(error) {
console.error("Failed to send user password reset email: " + error);
});
Deletes the account of the current Firebase user signed into the app.
Parameters:
FirebasePlugin.deleteUser(function() {
console.log("User account deleted");
}, function(error) {
console.error("Failed to delete current user account: " + error);
});
Creates a new email/password-based user account. If account creation is successful, user will be automatically signed in.
Parameters:
Example usage:
FirebasePlugin.createUserWithEmailAndPassword(email, password, function() {
console.log("Successfully created email/password-based user account");
// User is now signed in
}, function(error) {
console.error("Failed to create email/password-based user account", error);
});
Signs in to an email/password-based user account.
Parameters:
Example usage:
FirebasePlugin.signInUserWithEmailAndPassword(email, password, function() {
console.log("Successfully signed in");
// User is now signed in
}, function(error) {
console.error("Failed to sign in", error);
});
Signs in user with custom token.
Parameters:
Example usage:
FirebasePlugin.signInUserWithCustomToken(customToken, function() {
console.log("Successfully signed in");
// User is now signed in
}, function(error) {
console.error("Failed to sign in", error);
});
Signs in user anonymously.
Parameters:
Example usage:
FirebasePlugin.signInUserAnonymously(function() {
console.log("Successfully signed in");
// User is now signed in
}, function(error) {
console.error("Failed to sign in", error);
});
Requests verification of a phone number. The resulting credential can be used to create/sign in to a phone number-based user account in your app or to link the phone number to an existing user account
NOTE: This will only work on physical devices with a SIM card (not iOS Simulator or Android Emulator)
In response to your request, you'll receive a verification ID which you can use in conjunction with the verification code to sign the user in.
There are 3 verification scenarios:
Parameters:
The success callback will be passed a credential object with the following possible properties:
true if the Android device used instant verification to instantly verify the user without sending an SMS
or used auto-retrieval to automatically read an incoming SMS.
If this is false, the device will be sent an SMS containing the verification code.
If the Android device supports auto-retrieval, on the device receiving the SMS, this success callback will be immediately invoked again with instantVerification: true and no user action will be required for verification since Google Play services will extract and submit the verification code.
Otherwise the user must manually enter the verification code from the SMS into your app.
Always false on iOS.instantVerification is true.instantVerification is false.Example usage:
var number = '+441234567890';
var timeOutDuration = 60;
var fakeVerificationCode = '123456';
var awaitingSms = false;
FirebasePlugin.verifyPhoneNumber(function(credential) {
if(credential.instantVerification){
if(awaitingSms){
awaitingSms = false;
// the Android device used auto-retrieval to extract and submit the verification code in the SMS so dismiss user input UI
dismissUserPromptToInputCode();
}
signInWithCredential(credential);
}else{
awaitingSms = true;
promptUserToInputCode() // you need to implement this
.then(function(userEnteredCode){
awaitingSms = false;
credential.code = userEnteredCode; // set the user-entered verification code on the credential object
signInWithCredential(credential);
});
}
}, function(error) {
console.error("Failed to verify phone number: " + JSON.stringify(error));
}, number, timeOutDuration, fakeVerificationCode);
function signInWithCredential(credential){
FirebasePlugin.signInWithCredential(credential, function() {
console.log("Successfully signed in");
}, function(error) {
console.error("Failed to sign in", error);
});
}
To use phone auth with your Android app, you need to configure your app SHA-1 hash in the android app configuration in the Firebase console. See this guide to find how to your SHA-1 app hash. See the Firebase phone auth integration guide for native Android for more information.
When you call this method on iOS, FCM sends a silent push notification to the iOS device to verify it. So to use phone auth with your iOS app, you need to:
You can set up reCAPTCHA verification for iOS automatically by specifying the SETUP_RECAPTCHA_VERIFICATION plugin variable at plugin install time:
cordova plugin add cordova-plugin-firebasex --variable SETUP_RECAPTCHA_VERIFICATION=true
This adds the REVERSED_CLIENT_ID from the GoogleService-Info.plist to the list of custom URL schemes in your Xcode project, so you don't need to do this manually.
Sets the user-facing language code for auth operations that can be internationalized, such as sendEmailVerification() or verifyPhoneNumber(). This language code should follow the conventions defined by the IETF in BCP47.
Parameters:
Example usage:
FirebasePlugin.setLanguageCode('fr'); // will switch to french
Authenticates the user with email/password-based user account to obtain a credential that can be used to sign the user in/link to an existing user account/reauthenticate the user.
Parameters:
Example usage:
FirebasePlugin.authenticateUserWithEmailAndPassword(email, password, function(credential) {
console.log("Successfully authenticated with email/password");
FirebasePlugin.reauthenticateWithCredential(credential, function() {
console.log("Successfully re-authenticated");
}, function(error) {
console.error("Failed to re-authenticate", error);
});
// User is now signed in
}, function(error) {
console.error("Failed to authenticate with email/password", error);
});
Authenticates the user with a Google account to obtain a credential that can be used to sign the user in/link to an existing user account/reauthenticate the user.
Parameters:
Example usage:
FirebasePlugin.authenticateUserWithGoogle(clientId, function(credential) {
FirebasePlugin.signInWithCredential(credential, function() {
console.log("Successfully signed in");
}, function(error) {
console.error("Failed to sign in", error);
});
}, function(error) {
console.error("Failed to authenticate with Google: " + error);
});
To use Google Sign-in in your Android app you need to do the following:
For details how to do the above, see the Google Sign-In on Android page in the Firebase documentation.
Authenticates the user with an Apple account using Sign In with Apple to obtain a credential that can be used to sign the user in/link to an existing user account/reauthenticate the user.
To use Sign In with Apple you must ensure your app's provisioning profile has this capability and it is enabled in your Xcode project.
You can enable the capability in Xcode by setting the IOS_ENABLE_APPLE_SIGNIN plugin variable at plugin installation time:
cordova plugin add cordova-plugin-firebasex --variable IOS_ENABLE_APPLE_SIGNIN=true
Parameters:
Example usage:
FirebasePlugin.authenticateUserWithApple(function(credential) {
FirebasePlugin.signInWithCredential(credential, function() {
console.log("Successfully signed in");
}, function(error) {
console.error("Failed to sign in", error);
});
}, function(error) {
console.error("Failed to authenticate with Apple: " + error);
}, 'en_GB');
To use Sign In with Apple in your iOS app you need to do the following:
cordova-ios platform, open the project workspace in Xcode (platforms/ios/YourApp.xcworkspace) and add the "Sign In with Apple" capability in the "Signing & Capabilities section"
To use Sign In with Apple in your Android app you need to do the following:
Signs the user into Firebase with credentials obtained via an authentication method such as verifyPhoneNumber() or authenticateUserWithGoogle().
See the Android- and iOS-specific Firebase documentation for more info.
Parameters:
verifyPhoneNumber() and instantVerification is true, or if another authentication method was used such as authenticateUserWithGoogle().verifyPhoneNumber()verifyPhoneNumber() and instantVerification is false.verifyPhoneNumber() and instantVerification is false, you must set this to the activation code value as entered by the user from the received SMS message.Example usage:
function signInWithCredential(credential){
FirebasePlugin.signInWithCredential(credential, function() {
console.log("Successfully signed in");
}, function(error) {
console.error("Failed to sign in", error);
});
}
Links an existing Firebase user account with credentials obtained via an authentication method such as verifyPhoneNumber() or authenticateUserWithGoogle().
See the Android- and iOS-specific Firebase documentation for more info.
Parameters:
verifyPhoneNumber() and instantVerification is true, or if another authentication method was used such as authenticateUserWithGoogle().verifyPhoneNumber()verifyPhoneNumber() and instantVerification is false.verifyPhoneNumber() and instantVerification is false, you must set this to the activation code value as entered by the user from the received SMS message.Example usage:
function linkUserWithCredential(credential){
FirebasePlugin.linkUserWithCredential(credential, function() {
console.log("Successfully linked");
}, function(error) {
console.error("Failed to link", error);
});
}
Reauthenticates the currently signed in user with credentials obtained via an authentication method such as verifyPhoneNumber() or authenticateUserWithGoogle().
Parameters:
verifyPhoneNumber() and instantVerification is true, or if another authentication method was used such as authenticateUserWithGoogle().verifyPhoneNumber()verifyPhoneNumber() and instantVerification is false.verifyPhoneNumber() and instantVerification is false, you must set this to the activation code value as entered by the user from the received SMS message.Example usage:
FirebasePlugin.reauthenticateWithCredential(credential, function() {
console.log("Successfully reauthenticated");
}, function(error) {
console.error("Failed to reauthenticate", error);
});
Registers a Javascript function to invoke when Firebase Authentication state changes between user signed in/signed out.
Parameters:
true if user just signed in and false if user just signed out.Example usage:
FirebasePlugin.registerAuthStateChangeListener(function(userSignedIn){
console.log("Auth state changed: User signed " + (userSignedIn ? "in" : "out"));
});
Fetch Remote Config parameter values for your app:
Parameters:
FirebasePlugin.fetch(function () {
// success callback
}, function () {
// error callback
});
// or, specify the cacheExpirationSeconds
FirebasePlugin.fetch(600, function () {
// success callback
}, function () {
// error callback
});
Activate the Remote Config fetched config:
Parameters:
FirebasePlugin.activateFetched(function(activated) {
// activated will be true if there was a fetched config activated,
// or false if no fetched config was found, or the fetched config was already activated.
console.log(activated);
}, function(error) {
console.error(error);
});
Fetches and activates the Remote Config in a single operation.
Parameters:
FirebasePlugin.fetchAndActivate(function(activated) {
// activated will be true if there was a fetched config activated,
// or false if no fetched config was found, or the fetched config was already activated.
console.log(activated);
}, function(error) {
console.error(error);
});
Deletes all activated, fetched and defaults configs and resets all Firebase Remote Config settings.
Android only.
Parameters:
FirebasePlugin.resetRemoteConfig(function() {
console.log("Successfully reset remote config");
}, function(error) {
console.error("Error resetting remote config: " + error);
});
Retrieve a Remote Config value:
Parameters:
boolean, integer) you should cast the value to the appropriate type.FirebasePlugin.getValue("key", function(value) {
console.log(value);
}, function(error) {
console.error(error);
});
Get the current state of the FirebaseRemoteConfig singleton object:
Parameters:
FirebasePlugin.getInfo(function(info) {
// how many (secs) fetch cache is valid and data will not be refetched
console.log(info.configSettings.minimumFetchInterval);
// value in seconds to abandon a pending fetch request made to the backend
console.log(info.configSettings.fetchTimeout);
// the timestamp (milliseconds since epoch) of the last successful fetch
console.log(info.fetchTimeMillis);
// the status of the most recent fetch attempt (int)
// 0 = Config has never been fetched.
// 1 = Config fetch succeeded.
// 2 = Config fetch failed.
// 3 = Config fetch was throttled.
console.log(info.lastFetchStatus);
}, function(error) {
console.error(error);
});
Returns all Remote Config as key/value pairs
Parameters:
FirebasePlugin.getAll(function(values) {
for(var key in values){
console.log(key + "=" + values[key]);
}
}, function(error) {
console.error(error);
});
Changes the default Remote Config settings:
Parameters:
null value to omit setting this value.null value to omit setting this value.0 to disable minimum interval entirely (DO NOT do this in production)var fetchTimeout = 60;
var minimumFetchInterval = 3600;
FirebasePlugin.setConfigSettings(fetchTimeout, minimumFetchInterval, function(){
console.log("Successfully set Remote Config settings");
}, function(error){
console.error("Error setting Remote Config settings: " + error);
});
Sets in-app default values for your Remote Config parameters until such time as values are populated from the remote service via a fetch/activate operation.
Parameters:
// define defaults
var defaults = {
my_int: 1,
my_double: 3.14,
my_boolean: true,
my_string: 'hello world',
my_json: {"foo": "bar"}
}
// set defaults
FirebasePlugin.setDefaults(defaults);
Manually enable/disable performance data collection, e.g. if disabled on app startup.
Parameters:
FirebasePlugin.setPerformanceCollectionEnabled(true); // Enables performance data collection
FirebasePlugin.setPerformanceCollectionEnabled(false); // Disables performance data collection
Indicates whether performance data collection is enabled.
Notes:
true.Parameters:
FirebasePlugin.isPerformanceCollectionEnabled(function(enabled){
console.log("Performance data collection is "+(enabled ? "enabled" : "disabled"));
}, function(error){
console.error("Error getting Performance data collection setting: "+error);
});
Start a trace.
Parameters:
FirebasePlugin.startTrace("test trace", success, error);
To count the performance-related events that occur in your app (such as cache hits or retries), add a line of code similar to the following whenever the event occurs, using a string other than retry to name that event if you are counting a different type of event:
Parameters:
FirebasePlugin.incrementCounter("test trace", "retry", success, error);
Stop the trace
Parameters:
FirebasePlugin.stopTrace("test trace");
These plugin API functions provide CRUD operations for working with documents in Firestore collections.
Notes:
string, number, boolean, array or object.
Arrays and objects may contain nested structures of these types.Adds a new document to a Firestore collection, which will be allocated an auto-generated document ID.
Parameters:
var document = {
"a_string": "foo",
"a_list": [1, 2, 3],
"an_object": {
"an_integer": 1,
}
};
var collection = "my_collection";
FirebasePlugin.addDocumentToFirestoreCollection(document, collection, function(documentId){
console.log("Successfully added document with id="+documentId);
}, function(error){
console.error("Error adding document: "+error);
});
Sets (adds/replaces) a document with the given ID in a Firestore collection.
Parameters:
var documentId = "my_doc";
var document = {
"a_string": "foo",
"a_list": [1, 2, 3],
"an_object": {
"an_integer": 1,
}
};
var collection = "my_collection";
FirebasePlugin.setDocumentInFirestoreCollection(documentId, document, collection, function(){
console.log("Successfully set document with id="+documentId);
}, function(error){
console.error("Error setting document: "+error);
});
Updates an existing document with the given ID in a Firestore collection. This is a non-destructive update that will only overwrite existing keys in the existing document or add new ones if they don't already exist. If the no document with the specified ID exists in the collection, an error will be raised.
Parameters:
var documentId = "my_doc";
var documentFragment = {
"a_string": "new value",
"a_new_string": "bar"
};
var collection = "my_collection";
FirebasePlugin.updateDocumentInFirestoreCollection(documentId, documentFragment, collection, function(){
console.log("Successfully updated document with id="+documentId);
}, function(error){
console.error("Error updating document: "+error);
});
Deletes an existing document with the given ID in a Firestore collection.
Note: If the no document with the specified ID exists in the collection, the Firebase SDK will still return a successful outcome.
Parameters:
var documentId = "my_doc";
var collection = "my_collection";
FirebasePlugin.deleteDocumentFromFirestoreCollection(documentId, collection, function(){
console.log("Successfully deleted document with id="+documentId);
}, function(error){
console.error("Error deleting document: "+error);
});
Indicates if a document with the given ID exists in a Firestore collection.
Parameters:
true if a document exists.var documentId = "my_doc";
var collection = "my_collection";
FirebasePlugin.documentExistsInFirestoreCollection(documentId, collection, function(exists){
console.log("Document " + (exists ? "exists" : "doesn't exist"));
}, function(error){
console.error("Error fetching document: "+error);
});
Fetches an existing document with the given ID from a Firestore collection.
Note: If the no document with the specified ID exists in the collection, the error callback will be invoked.
Parameters:
var documentId = "my_doc";
var collection = "my_collection";
FirebasePlugin.fetchDocumentInFirestoreCollection(documentId, collection, function(document){
console.log("Successfully fetched document: "+JSON.stringify(document));
}, function(error){
console.error("Error fetching document: "+error);
});
Fetches all the documents in the specific collection.
Parameters:
{string} collection - name of top-level collection to fetch.
{array} filters (optional) - a list of filters to sort/filter the documents returned from your collection.
where, orderBy, startAt, endAt and limit filters.
where: [where, fieldName, operator, value, valueType]
fieldName - name of field to matchoperator - operator to apply to match
==, <, >, <=, >=, array-containsvalue - field value to matchvalueType (optional) - type of variable to fetch value as
string, boolean, integer, double, longstringstartAt: [startAt, value, valueType]
value - field value to start atvalueType (optional) - type of variable to fetch value as (as above)endAt: [endAt, value, valueType]
value - field value to end atvalueType (optional) - type of variable to fetch value as (as above)orderBy: [orderBy, fieldName, sortDirection]
fieldName - name of field to order bysortDirection - direction to order in: asc or desclimit: [limit, value]
value - integer defining maximum number of results to return.{function} success - callback function to call on successfully deleting the document. Will be passed an {object} containing all the documents in the collection, indexed by document ID. If a Firebase collection with that name does not exist or it contains no documents, the object will be empty.
{function} error - callback function which will be passed a {string} error message as an argument.
var collection = "my_collection";
var filters = [
['where', 'my_string', '==', 'foo'],
['where', 'my_integer', '>=', 0, 'integer'],
['where', 'my_boolean', '==', true, 'boolean'],
['orderBy', 'an_integer', 'desc'],
['startAt', 'an_integer', 10, 'integer'],
['endAt', 'an_integer', 100, 'integer'],
['limit', 100000]
];
FirebasePlugin.fetchFirestoreCollection(collection, filters, function(documents){
console.log("Successfully fetched collection: "+JSON.stringify(documents));
}, function(error){
console.error("Error fetching collection: "+error);
});
Adds a listener to detect real-time changes to the specified document.
Upon adding a listener using this function, the success callback function will be invoked with an id event which specifies the native ID of the added listener.
This can be used to subsequently remove the listener using removeFirestoreListener().
For example:
{
"eventType": "id",
"id": 12345
}
The callback will also be immediately invoked again with a change event which contains a snapshot of the document at the time of adding the listener.
Then each time the document is changed, either locally or remotely, the callback will be invoked with another change event detailing the change.
Event fields:
source - specifies if the change was local (made locally on the app) or remote (made via the server).fromCache - specifies whether the snapshot was read from local cachesnapshot - a snapshot of document at the time of the change.
For example:
{
"eventType": "change",
"source": "remote",
"fromCache": true,
"snapshot": {
"a_field": "a_value"
}
}
See the Firestore documentation for more info on real-time listeners.
Parameters:
id or change event.false.var documentId = "my_doc";
var collection = "my_collection";
var includeMetadata = true;
var listenerId;
FirebasePlugin.listenToDocumentInFirestoreCollection(function(event){
switch(event.eventType){
case "id":
listenerId = event.id;
console.log("Successfully added document listener with id="+listenerId);
break;
case "change":
console.log("Detected document change");
console.log("Source of change: " + event.source);
console.log("Read from local cache: " + event.fromCache);
if(event.snapshot){
console.log("Document snapshot: " + JSON.stringify(event.snapshot));
}
break;
}
}, function(error){
console.error("Error adding listener: "+error);
}, documentId, collection, includeMetadata);
Adds a listener to detect real-time changes to documents in a Firestore collection.
Upon adding a listener using this function, the success callback function will be invoked with an id event which specifies the native ID of the added listener.
This can be used to subsequently remove the listener using removeFirestoreListener().
For example:
{
"eventType": "id",
"id": 12345
}
The callback will also be immediately invoked again with a change event which contains a snapshot of all documents in the collection at the time of adding the listener.
Then each time document(s) in the collection change, either locally or remotely, the callback will be invoked with another change event detailing the change.
Event fields:
documents - key/value list of document changes indexed by document ID. For each document change:
source - specifies if the change was local (made locally on the app) or remote (made via the server).fromCache - specifies whether the snapshot was read from local cachetype - specifies the change type:
added - document was added to collectionmodified - document was modified in collectionremoved - document was removed from collectionmetadata - document metadata changedsnapshot - a snapshot of document at the time of the change.
For example:
{
"eventType": "change",
"documents":{
"a_doc": {
"source": "remote",
"fromCache": false,
"type": "added",
"snapshot": {
"a_field": "a_value"
}
},
"another_doc": {
"source": "remote",
"fromCache": false,
"type": "removed",
"snapshot": {
"foo": "bar"
}
}
}
}
See the Firestore documentation for more info on real-time listeners.
Parameters:
id or change event.false.var collection = "my_collection";
var filters = [
['where', 'field', '==', 'value'],
['orderBy', 'field', 'desc']
];
var includeMetadata = true;
var listenerId;
FirebasePlugin.listenToFirestoreCollection(function(event){
switch(event.eventType){
case "id":
listenerId = event.id;
console.log("Successfully added collection listener with id="+listenerId);
break;
case "change":
console.log("Detected collection change");
if(event.documents){
for(var documentId in event.documents){
console.log("Document ID: " + documentId);
var docChange = event.documents[documentId];
console.log("Source of change: " + docChange.source);
console.log("Change type: " + docChange.type);
console.log("Read from local cache: " + docChange.fromCache);
if(docChange.snapshot){
console.log("Document snapshot: " + JSON.stringify(docChange.snapshot));
}
}
}
break;
}
}, function(error){
console.error("Error adding listener: "+error);
}, collection, filters, includeMetadata);
Removes an existing native Firestore listener (see detaching listeners) added with listenToDocumentInFirestoreCollection() or listenToFirestoreCollection().
Upon adding a listener using either of the above functions, the success callback function will be invoked with an id event which specifies the native ID of the added listener.
For example:
{
"eventType": "id",
"id": 12345
}
This can be used to subsequently remove the listener using this function.
You should remove listeners when you're not using them as while active they maintain a continual HTTP connection to the Firebase servers costing memory, bandwith and money: see best practices for realtime updates and billing for realtime updates.
Parameters:
FirebasePlugin.removeFirestoreListener(function(){
console.log("Successfully removed listener");
}, function(error){
console.error("Error removing listener: "+error);
}, listenerId);
FAQs
Cordova plugin for Google Firebase
We found that cordova-plugin-firebasex-with-upstream-messaging demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
pnpm 10 blocks lifecycle scripts by default to improve security, addressing supply chain attack risks but sparking debate over compatibility and workflow changes.
Product
Socket now supports uv.lock files to ensure consistent, secure dependency resolution for Python projects and enhance supply chain security.
Research
Security News
Socket researchers have discovered multiple malicious npm packages targeting Solana private keys, abusing Gmail to exfiltrate the data and drain Solana wallets.