cordova-plugin-firebasex

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.

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.

MAINTENANCE OF THIS PLUGIN: Please note this plugin is maintained only by me - one person - in my spare time: I do not get paid for it. Therefore I will do my best to address bugs and issues as time permits but if you have an urgent requirement for a bug fix or missing feature, then I am available for paid contract work in order to expedite this - contact me for details. Otherwise I will get around to it when I have time.

• Installation
  • Plugin variables
    • Android & iOS
    • Android only
    • iOS only
    • Post-install plugin variables
  • Supported Cordova Versions
  • Supported Mobile Platform Versions
  • Migrating from cordova-plugin-firebase
    • Breaking API changes
    • Ionic 4+
    • Ionic 3
• Build environment notes
  • Remote Cloud Build
  • Capacitor support
  • Android-specific
    • Specifying Android library versions
    • AndroidX
  • Google Play Services and Firebase libraries
  • iOS-specific
    • Specifying iOS library versions
    • Cocoapods
    • Out-of-date pods
    • Strip debug symbols
    • Cordova CLI builds
• Firebase config setup
• Disable data collection on startup
• Example project
• Reporting issues
  • Reporting a bug or problem
  • Requesting a new feature
• Cloud messaging
  • Background notifications
  • Foreground notifications
  • Android notifications
    • Android background notifications
    • Android foreground notifications
    • Android Notification Channels
    • Android Notification Icons
    • Android Notification Color
    • Android Notification Sound
    • Android cloud message types
  • iOS notifications
    • iOS background notifications
    • iOS notification sound
    • iOS critical notifications
    • iOS badge number
    • iOS actionable notifications
    • iOS notification settings button
  • Data messages
    • Data message notifications
  • Custom FCM message handling
    • Android
    • iOS
    • Example
• InApp Messaging
• Google Tag Manager
  • Android
  • iOS
• Performance Monitoring
  • Android Performance Monitoring Gradle plugin
• API
  • Notifications and data messages
    • getToken
    • getId
    • onTokenRefresh
    • getAPNSToken
    • onApnsTokenReceived
    • onOpenSettings
    • onMessageReceived
    • grantPermission
    • grantCriticalPermission
    • hasPermission
    • hasCriticalPermission
    • unregister
    • isAutoInitEnabled
    • setAutoInitEnabled
    • setBadgeNumber
    • getBadgeNumber
    • clearAllNotifications
    • subscribe
    • unsubscribe
    • createChannel
    • setDefaultChannel
    • Default Android Channel Properties
    • deleteChannel
    • listChannels
  • Analytics
    • setAnalyticsCollectionEnabled
    • isAnalyticsCollectionEnabled
    • AnalyticsConsentMode
    • AnalyticsConsentStatus
    • setAnalyticsConsentMode
    • logEvent
    • setScreenName
    • setUserId
    • setUserProperty
    • initiateOnDeviceConversionMeasurement
  • Crashlytics
    • setCrashlyticsCollectionEnabled
    • didCrashOnPreviousExecution
    • isCrashlyticsCollectionEnabled
    • setCrashlyticsUserId
    • sendCrash
    • setCrashlyticsCustomKey
    • logMessage
    • logError
  • Authentication
    • isUserSignedIn
    • signOutUser
    • getCurrentUser
    • reloadCurrentUser
    • updateUserProfile
    • updateUserEmail
    • sendUserEmailVerification
    • verifyBeforeUpdateEmail
    • updateUserPassword
    • sendUserPasswordResetEmail
    • deleteUser
    • createUserWithEmailAndPassword
    • signInUserWithEmailAndPassword
    • signInUserWithCustomToken
    • signInUserAnonymously
    • verifyPhoneNumber
    • enrollSecondAuthFactor
    • verifySecondAuthFactor
    • listEnrolledSecondAuthFactors
    • unenrollSecondAuthFactor
    • setLanguageCode
    • authenticateUserWithEmailAndPassword
    • authenticateUserWithGoogle
    • authenticateUserWithApple
    • authenticateUserWithMicrosoft
    • authenticateUserWithFacebook
    • authenticateUserWithOAuth
    • signInWithCredential
    • linkUserWithCredential
    • reauthenticateWithCredential
    • unlinkUserWithProvider
    • registerAuthStateChangeListener
    • registerAuthIdTokenChangeListener
    • useAuthEmulator
    • getClaims
  • Remote Config
    • fetch
    • activateFetched
    • fetchAndActivate
    • resetRemoteConfig
    • getValue
    • getInfo
    • getAll
    • setConfigSettings
    • setDefaults
  • Performance
    • setPerformanceCollectionEnabled
    • isPerformanceCollectionEnabled
    • startTrace
    • incrementCounter
    • stopTrace
  • Firestore
    • addDocumentToFirestoreCollection
    • setDocumentInFirestoreCollection
    • updateDocumentInFirestoreCollection
    • deleteDocumentFromFirestoreCollection
    • documentExistsInFirestoreCollection
    • fetchDocumentInFirestoreCollection
    • fetchFirestoreCollection
    • listenToDocumentInFirestoreCollection
    • listenToFirestoreCollection
    • removeFirestoreListener
  • Functions
    • functionsHttpsCallable
  • Installations
    • getInstallationId
    • getInstallationToken
    • getInstallationId
    • registerInstallationIdChangeListener
  • Miscellaneous
    • registerApplicationDidBecomeActiveListener
    • registerApplicationDidEnterBackgroundListener
    • Debug mode
• Credits

Installation

Install the plugin by adding it to your project's config.xml:

<plugin name="cordova-plugin-firebasex" spec="latest" />

or by running:

cordova plugin add cordova-plugin-firebasex

Plugin variables

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.

Plugin variables are initially set by specifying them during plugin installation, for example: cordova plugin add cordova-plugin-firebasex --variable FIREBASE_ANALYTICS_WITHOUT_ADS=true

Once the plugin is installed, you can change the plugin variable values either by fully uninstalling/reinstalling the plugin, for example: cordova plugin rm cordova-plugin-firebasex && cordova plugin add cordova-plugin-firebasex --variable FIREBASE_ANALYTICS_WITHOUT_ADS=false

Or you can manually edit the values in your project's package.json under cordova.plugins.cordova-plugin-firebasex and reinstall the plugin: cordova plugin rm cordova-plugin-firebasex --nosave && cordova plugin add cordova-plugin-firebasex --nosave

Android & iOS

• FIREBASE_ANALYTICS_COLLECTION_ENABLED - whether to automatically enable Firebase Analytics data collection on app startup. Defaults to true.
• FIREBASE_PERFORMANCE_COLLECTION_ENABLED - whether to automatically enable Firebase Performance data collection on app startup. Defaults to true.
• FIREBASE_CRASHLYTICS_COLLECTION_ENABLED - whether to automatically enable Firebase Crashlytics data collection on app startup. Defaults to true.
• FIREBASE_FCM_AUTOINIT_ENABLED - whether to automatically enable FCM registration on app startup. Defaults to true.
• FIREBASE_ANALYTICS_WITHOUT_ADS - whether to disable advertising ID collection in Analytics. Defaults to false.
  • Note that this is a post-install plugin variable so an additional step is required to activate the plugin variable the first time it is specified. See Disable data collection on startup for more info.
• FIREBASE_MESSAGING_IMMEDIATE_PAYLOAD_DELIVERY - whether to deliver FCM messages immediately when the app is in the background. Defaults to false.
• If false, messages that arrive while the app is in the background/inactive are queued and delivered when the app is next brought to the foreground.
• If true, messages are delivered immediately when received, even if the app is in the background/inactive.
  • Note: on modern iOS and Android devices, there is no guarantee that the message will be successfully delivered to the app because the OS may have paused the app's Cordova Webview process or the Webview may not exist at the time the message is received.
• GOOGLE_ANALYTICS_ADID_COLLECTION_ENABLED - determines whether Google Analytics collects Advertising IDs (ADIDs) for ad targeting and attribution purposes. If set to true, Google Analytics will collect ADIDs; if set to false, it will not collect ADIDs. Defaults to true.
• GOOGLE_ANALYTICS_DEFAULT_ALLOW_ANALYTICS_STORAGE - specifies the default setting for allowing Google Analytics to store analytics data. If set to true, Google Analytics is allowed to store analytics data; if set to false, it is not allowed to store analytics data by default.
• GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_STORAGE - specifies the default setting for allowing Google Analytics to store ad-related data. If set to true, Google Analytics is allowed to store ad-related data; if set to false, it is not allowed to store ad-related data by default. Defaults to true.
• GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_USER_DATA - specifies the default setting for allowing Google Analytics to collect user-related data for ad targeting and personalization. If set to true, Google Analytics is allowed to collect user-related data for ad targeting and personalization; if set to false, it is not allowed to collect such data by default. Defaults to true.
• GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_PERSONALIZATION_SIGNALS - specifies the default setting for allowing Google Analytics to collect signals related to ad personalization. If set to true, Google Analytics is allowed to collect ad personalization signals; if set to false, it is not allowed to collect such signals by default. Defaults to true.

Android only

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_INAPPMESSAGING_VERSION

• ANDROID_FIREBASE_FIRESTORE_VERSION

• ANDROID_FIREBASE_FUNCTIONS_VERSION

• ANDROID_FIREBASE_INSTALLATIONS_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

  • e.g. --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.

  • e.g. --variable ANDROID_FIREBASE_PERFORMANCE_MONITORING=true
  • Defaults to false if not specified.

• ANDROID_FIREBASE_PERF_GRADLE_PLUGIN_VERSION - overrides the default version of the Firebase Performance Monitoring Gradle plugin for Android

• ANDROID_GRPC_OKHTTP - sets version of GRPC OKHTTP library.

iOS only

• IOS_FIREBASE_SDK_VERSION - a specific version of the Firebase iOS SDK to set in the Podfile
  • If not specified, the default version defined in <pod> elements in the plugin.xml will be used.
• IOS_FIREBASE_IN_APP_MESSAGING_VERSION - a specific version of the Firebase iOS InAppMessaging SDK to set in the Podfile
  • If not specified, the default version defined in <pod> elements in the plugin.xml will be used.
• IOS_GOOGLE_SIGIN_VERSION - a specific version of the Google Sign In library to set in the Podfile
  • If not specified, the default version defined in the <pod> element in the plugin.xml will be used.
• IOS_GOOGLE_TAG_MANAGER_VERSION - a specific version of the Google Tag Manager library to set in the Podfile
  • If not specified, the default version defined in the <pod> element in the plugin.xml will be used.
• IOS_USE_PRECOMPILED_FIRESTORE_POD - if true, switches Podfile to use a pre-compiled version of the Firestore pod to reduce build time
  • Defaults to false if not specified.
  • If you set this option to true, you must ensure the environment variable SKIP_FIREBASE_FIRESTORE_SWIFT is set globally to a truthy value
    • e.g. If using zsh: echo 'export SKIP_FIREBASE_FIRESTORE_SWIFT=1' >> ~/.zshrc && source ~/.zshrc
    • This ensures the pre-built pod is compatible with the Cordova project environment (see here)
  • Note that this is a post-install plugin variable so an additional step is required to activate the plugin variable the first time it is specified.
  • If you're having issues building with Firestore, see here for suggested solutions.
• IOS_STRIP_DEBUG - prevents symbolification of all libraries included via Cocoapods. See Strip debug symbols for more info.
  • e.g. --variable IOS_STRIP_DEBUG=true
  • Defaults to false if not specified.
• SETUP_RECAPTCHA_VERIFICATION - automatically sets up reCAPTCHA verification for phone authentication on iOS. See verifyPhoneNumber for more info.
  • e.g. --variable SETUP_RECAPTCHA_VERIFICATION=true
  • Defaults to false if not specified.
• IOS_SHOULD_ESTABLISH_DIRECT_CHANNEL - If true Firebase Messaging will automatically establish a socket-based, direct channel to the FCM server.
  • e.g. --variable IOS_SHOULD_ESTABLISH_DIRECT_CHANNEL=true
  • Defaults to false if not specified.
  • See shouldEstablishDirectChannel
  • Note: Firebase Messaging iOS SDK version 7.0 will be a breaking change where the SDK will no longer support iOS Direct Channel API.
• IOS_FIREBASE_CONFIG_FILEPATH - sets a custom filepath to GoogleService-Info.plist file as a path relative to the project root
  • e.g. --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
  • Ensure the associated app provisioning profile also has this capability enabled.
• IOS_ENABLE_CRITICAL_ALERTS_ENABLED - enables the critical alerts capability
  • --variable IOS_ENABLE_CRITICAL_ALERTS_ENABLED=true
  • See iOS critical notifications
  • Ensure the associated app provisioning profile also has this capability enabled.
• IOS_FCM_ENABLED - allows to completely disable push notifications functionality of the plugin (not just the automatic initialization that is covered by FIREBASE_FCM_AUTOINIT_ENABLED variable).
  • Defaults to true, if not specified; i.e. FCM is enabled by default.
  • This can be handy if you are using this plugin for e.g. Crashlytics and handle push notifications using another plugin. Use --variable IOS_FCM_ENABLED=false in this case.
• IOS_ON_DEVICE_CONVERSION_ANALYTICS - whether to include the On-Device Conversion component of the Firebase SDK.
  • Defaults to false if not specified.
  • If true, the component will be included and initiateOnDeviceConversionMeasurement can be called at run-time to enable it.
  • Note that this is a post-install plugin variable so an additional step is required to activate the plugin variable the first time it is specified.

Post-install plugin variables

• Some of the plugin variables above are used to optionally include additional components of the Firebase SDKs.
• Since Cordova does not support using plugin variables to optionally include plugin dependencies, this plugin implements a custom npm post-install script to enable this behaviour.
• This script is executed automatically after the plugin is installed and will apply the plugin variables defined in your project's package.json to the plugin's plugin.xml file before Cordova parses the plugin.xml file.
• However, the first time you specify a new plugin variable, the post-install script will be executed before Cordova has added the plugin variable to the package.json file so the plugin variable will not be applied to the plugin.xml file.
• IMPORTANT: Therefore if you specify a plugin variable for the first time, you must reinstall the plugin for the plugin variable to be applied to the plugin.xml file:
  • e.g. cordova plugin rm cordova-plugin-firebasex --nosave && cordova plugin add cordova-plugin-firebasex --nosave
  • Note: you do not have to specify the plugin variable(s) again when reinstalling the plugin as they will be read from the package.json file.

Supported Cordova Versions

• cordova: >= 10
• cordova-android: >= 10
• cordova-ios: >= 6

Supported Mobile Platform Versions

The supported versions of Android and iOS depend on the version of the Firebase SDK included in the build.

See the Firebase iOS and Android release notes to determine the minimum support OS versions for the SDK version included in your build. If you didn't explicity specify a version for the Firebase SDK using plugin variables at plugin installation time, you can find the current default version in the plugin's plugin.xml.

Migrating from cordova-plugin-firebase

This 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

Breaking API changes

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:

• Minimum supported Cordova versions
  • cordova@10 (CLI)
  • cordova-android@10 (Android platform)
  • cordova-ios@6 (iOS platform)
• Migrated to AndroidX from legacy Android Support Library
• Migrated to Cocoapods to satisfy Firebase SDK dependencies on iOS
• 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|false
• hasPermission() receives argument as a boolean (rather than an object with isEnabled key)
  • e.g. FirebasePlugin.hasPermission(function(hasPermission){ console.log("Permission is " + (hasPermission ? "granted" : "denied")); });
• Adds support for foreground notifications and data notification messages

Ionic 4+

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:

• This plugin provides only the Javascript API as documented below.
• The Typescript wrapper is owned and maintain by Ionic.
• Please report any issues against the Ionic Native repo, not this one.
• Any issues opened against this repo which relate to the Typescript wrapper will be closed immediately.

Ionic 3

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.

Build environment notes

Remote Cloud Build

This plugin will not work with remote cloud build services that do not support Cordova hook scripts (e.g. Ionic Appflow). The hook scripts used by this plugin are essential to configure the native platform projects for use with the Firebase SDK and therefore if they are not executed, the plugin will not work correctly: either the build will fail or the app containing the plugin will crash at runtime.

Even if the remote build service supports Cordova hook scripts, it is hard to diagnose the cause of build issue because the environment is not under your direct control. Therefore a local build environment is highly recommended since you have full control and the ability to update/upgrade any components in the OS. Support for using this plugin can only be offered when building projects in a local environment. (i.e. your own development machine).

However if you are unable to build locally and therefore must use a remote build environment, then VoltBuilder is recommended for use with this plugin as it supports Cordova hook scripts and its developers have explicitly tested building with this plugin to ensure compatibility.

Capacitor support

This plugin does not currently support Capacitor. If you want to use Firebase with Capacitor, you should use Capacitor Firebase or the Firebase JS SDK instead.

This plugin is designed to work with Cordova therefore relies on Cordova features such as hook scripts, plugin variables and project structure in order to manipulate the native platform projects for use with the Firebase SDK.

Android-specific

Specifying Android library versions

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-tagmanager
• ANDROID_PLAY_SERVICES_AUTH_VERSION => com.google.android.gms:play-services-auth
• ANDROID_FIREBASE_ANALYTICS_VERSION => com.google.firebase:firebase-analytics
• ANDROID_FIREBASE_MESSAGING_VERSION => com.google.firebase:firebase-messaging
• ANDROID_FIREBASE_CONFIG_VERSION => com.google.firebase:firebase-config
• ANDROID_FIREBASE_PERF_VERSION => com.google.firebase:firebase-perf
• ANDROID_FIREBASE_AUTH_VERSION => com.google.firebase:firebase-auth
• ANDROID_FIREBASE_FIRESTORE_VERSION => com.google.firebase:firebase-firestore
• $ANDROID_FIREBASE_FUNCTIONS_VERSION => com.google.firebase:firebase-functions
• $ANDROID_FIREBASE_INSTALLATIONS_VERSION => com.google.firebase:firebase-installations
• $ANDROID_FIREBASE_INAPPMESSAGING_VERSION => com.google.firebase:firebase-inappmessaging-display
• ANDROID_FIREBASE_CRASHLYTICS_VERSION => com.google.firebase:firebase-crashlytics
• ANDROID_FIREBASE_CRASHLYTICS_NDK_VERSION => com.google.firebase:firebase-crashlytics-ndk
• ANDROID_GSON_VERSION => com.google.code.gson:gson

For 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 \

AndroidX

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

Google Play Services and Firebase libraries

Your Android build may fail if you are installing multiple plugins that use the Google Play Services library. This is caused by plugins installing different versions of the Google Play Services library. This can be resolved by installing cordova-android-play-services-gradle-release 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.

iOS-specific

Please ensure you have the latest Xcode release version installed to build your app - direct download links can be found here.

Specifying iOS library versions

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"/>

Cordova does not natively support the use of plugin variables in the <pod>'s spec attribute, however this plugin uses a hook script to enable this behaviour by overriding the version specified in plugin.xml directly within the Podfile. Therefore to override the version of the Firebase iOS SDK components set in the plugin.xml, you should define it using the IOS_FIREBASE_SDK_VERSION plugin variable when installing the plugin into your project. For example:

cordova plugin add cordova-plugin-firebasex --variable IOS_FIREBASE_SDK_VERSION=9.1.0

Cocoapods

This plugin relies on Cordova support for the CocoaPods dependency manager in order to satisfy the iOS Firebase SDK library dependencies.

Please make sure you have cocoapods@>=1.11.2 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

Out-of-date pods

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/.

Set up project to automatically upload dSYM files

Firebase Documentation Get started with Firebase Crashlytics

Make sure cordova-plugin-firebasex is last plugin in cordova section of your package.json

{
    ...
    "cordova": {
        "platforms": [
            "browser",
            "ios",
            "android"
        ],
        "plugins": {
            ...
            "cordova-plugin-firebasex": {
                ...
            }
        }
    },
    ....
}

Strip debug symbols

If your iOS app build contains too many debug symbols (i.e. because you include lots of libraries via a Cocoapods), you might get an error (e.g. issue #28) 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.

Cordova CLI builds

• Older versions of the Firebase Inapp Messaging SDK and Google Tag Manager SDK components caused build issues when building via the Cordova CLI.
• Therefore, the cli_build branch was kept in sync with master but without the above components.
• However, in recent versions, the Firebase Inapp Messaging SDK and Google Tag Manager SDK components no longer cause build issues when building via the Cordova CLI.
• Therefore, the cli_build branch is no longer maintained and the master branch should be used for Cordova CLI builds.

Firebase config setup

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.

Disable data collection on startup

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

• GOOGLE_ANALYTICS_ADID_COLLECTION_ENABLED

• GOOGLE_ANALYTICS_DEFAULT_ALLOW_ANALYTICS_STORAGE

• GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_STORAGE

• GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_USER_DATA

• GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_PERSONALIZATION_SIGNALS

  cordova plugin add cordova-plugin-firebasex
  --variable FIREBASE_ANALYTICS_COLLECTION_ENABLED=false
  --variable FIREBASE_PERFORMANCE_COLLECTION_ENABLED=false
  --variable FIREBASE_CRASHLYTICS_COLLECTION_ENABLED=false
  --variable GOOGLE_ANALYTICS_ADID_COLLECTION_ENABLED=false
  --variable GOOGLE_ANALYTICS_DEFAULT_ALLOW_ANALYTICS_STORAGE=false
  --variable GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_STORAGE=false
  --variable GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_USER_DATA=false
  --variable GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_PERSONALIZATION_SIGNALS=false

This will disable data collection (on both Android & iOS) until you call setAnalyticsCollectionEnabled, setPerformanceCollectionEnabled, setCrashlyticsCollectionEnabled and setAnalyticsConsentMode:

   FirebasePlugin.setAnalyticsCollectionEnabled(true);
   FirebasePlugin.setPerformanceCollectionEnabled(true);
   FirebasePlugin.setCrashlyticsCollectionEnabled(true);
   FirebasePlugin.setAnalyticsConsentMode({
       ANALYTICS_STORAGE: "GRANTED",
       AD_STORAGE: "GRANTED",
       AD_USER_DATA: "GRANTED",
       AD_PERSONALIZATION: "GRANTED",
   });

Notes:

• Calling setXCollectionEnabled() will have no effect if the corresponding FIREBASE_X_COLLECTION_ENABLED variable is set to true.
• Calling 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.

Example project

An example project repo exists to demonstrate and validate the functionality of this plugin: https://github.com/dpa99c/cordova-plugin-firebasex-test

Please use this as a working reference.

Before reporting any issues, please (if possible) test against the example project to rule out causes external to this plugin.

Reporting issues

IMPORTANT: Please read the following carefully. Failure to follow the issue template guidelines below will result in the issue being immediately closed.

Reporting a bug or problem

Before opening a bug issue, please do the following:

• DO NOT open issues asking for support in using/integrating the plugin into your project
  • Only open issues for suspected bugs/issues with the plugin that are generic and will affect other users
  • I don't have time to offer free technical support: this is free open-source software
  • Ask for help on StackOverflow, Ionic Forums, etc.
  • Use the example project as a known working reference
  • Any issues requesting support will be closed immediately.
• DO NOT open issues related to the Ionic Typescript wrapper for this plugin
  • This is owned/maintained by Ionic and is not part of this plugin
  • Please raise such issues/PRs against Ionic Native instead.
  • To verify an if an issue is caused by this plugin or its Typescript wrapper, please re-test using the vanilla Javascript plugin interface (without the Ionic Native wrapper).
  • Any issue opened here which is obviously an Ionic Typescript wrapper issue will be closed immediately.
• DO NOT open issues related to Remote Cloud Build environments such as Ionic Appflow as these are not supported
• If you are migrating from cordova-plugin-firebase to cordova-plugin-firebasex please make sure you have read the Migrating from cordova-plugin-firebase section.
• Read the above documentation thoroughly
  • For example, if you're having a build issue ensure you've read through the build environment notes
  • If an iOS CLI build is failing, ensure you've read the Cordova CLI builds section
• Check the CHANGELOG for any breaking changes that may be causing your issue.
• Check a similar issue (open or closed) does not already exist against this plugin.
  • Duplicates or near-duplicates will be closed immediately.
• When creating a new issue
  • Choose the "Bug report" template
  • Fill out the relevant sections of the template and delete irrelevant sections
  • WARNING: Failure to complete the issue template will result in the issue being closed immediately.
• Reproduce the issue using the example project
  • This will eliminate bugs in your code or conflicts with other code as possible causes of the issue
  • This will also validate your development environment using a known working codebase
  • If reproducing the issue using the example project is not possible, create an isolated test project that you are able to share
  • Support cannot be offered to help resolve build issues in your own project.
• Include full verbose console output when reporting build issues
  • If the full console output is too large to insert directly into the Github issue, then post it on an external site such as Pastebin and link to it from the issue
  • Often the details of an error causing a build failure is hidden away when building with the CLI
    • To get the full detailed console output, append the --verbose flag to CLI build commands
    • e.g. cordova build ios --verbose
  • Failure to include the full console output will result in the issue being closed immediately
• If the issue relates to the plugin documentation (and not the code), please of a documentation issue

Requesting a new feature

Before opening a feature request issue, please do the following:

• Check the above documentation to ensure the feature you are requesting doesn't already exist
• Check the list if open/closed issues to check if there's a reason that feature hasn't been included already
• Ensure the feature you are requesting is actually possible to implement and generically useful to other users than yourself
• Where possible, post a link to the documentation related to the feature you are requesting
• Include other relevant links, e.g.
  • Stack Overflow post illustrating a solution
  • Code within another Github repo that illustrates a solution

Cloud messaging

 

There are 2 distinct types of messages that can be sent by Firebase Cloud Messaging (FCM):

• Notification messages
  • automatically displayed to the user by the operating system on behalf of the client app while your app is not running or is in the background
    • if your app is in the foreground when the notification message arrives, it is passed to the client app and it is the responsibility of the client app to display it.
  • have a predefined set of user-visible keys and an optional data payload of custom key-value pairs.
• Data messages
  • Client app is responsible for processing data messages.
  • Data messages have only custom key-value pairs.

Note: only notification messages can be sent via the Firebase Console - data messages must be sent via the FCM APIs.

Background notifications

If the notification message arrives while the app is in the background/not running, it will be displayed as a system notification.

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".

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 a message arrives while the app is in the background or is inactive, that doesn't require user interaction to receive the message payload - see Android background notifications and iOS background notifications for details.

Foreground notifications

If the notification message arrives while the app is in running in the foreground, by default it will NOT be displayed as a system notification. Instead the notification message payload will be passed to the onMessageReceived 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.

Android notifications

Notifications on Android can be customised to specify the sound, icon, LED colour, etc. that's displayed when the notification arrives.

Android background notifications

If the notification message arrives while the app is in the background/not running, it will be displayed as a system notification.

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.

If a notification message arrives while the app is in the background or inactive, it will be queued until the next time the app is resumed into the foreground. This is to ensure the Cordova application running in the Webview is in a state where it can receive the notification message. Upon resuming, each queued notification will be sent to the onMessageReceived callback without the tap property, indicating the message was received without user interaction.

If you wish to attempt to immediately deliver the message payload to the onMessageReceived callback when the app is in the background or inactive (the default behaviour of this plugin prior to v18), you can set the FIREBASE_MESSAGING_IMMEDIATE_PAYLOAD_DELIVERY plugin variable to true at plugin install time:

cordova plugin add cordova-plugin-firebasex --variable FIREBASE_MESSAGING_IMMEDIATE_PAYLOAD_DELIVERY=true

However there is no guarantee that the message will be delivered successfully, since the Cordova application running in the Webview may not be in a state where it can receive the notification message.

In addition to the title and body of the notification message, Android system notifications support specification of the following notification settings:

• Icon
• Sound
• Color accent
• Channel ID (Android 8.0 (O) and above)
  • This channel configuration enables you to specify:
    • Sound
    • Vibration
    • LED light
    • Badge
    • Importance
    • Visibility
  • See createChannel for details.

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"
    }
}

Android foreground notifications

If the notification message arrives while the app is in the foreground, by default a system notification won't be displayed and the data will be passed to onMessageReceived.

However, if you set the notification_foreground key in the data section of the notification message payload, this will cause the plugin to display system notification when the message is received while your app is in the foreground. You can customise the notification using the same keys as for Android data message notifications.

Android Notification Channels

• Android 8 (O) introduced notification channels.
• Notification channels are configured by the app and used to determine the sound/lights/vibration settings of system notifications.
• By default, this plugin creates a default channel with default properties
  • These can be overridden via the setDefaultChannel function.
• The plugin enables the creation of additional custom channels via the createChannel function.

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"
        }
    }
}

Android 7 and below

• the channel referenced in the message payload will be ignored
• the sound setting of system notifications is specified in the notification message itself - see Android Notification Sound.

Android Notification Icons

By default the plugin will use the default app icon for notification messages.

Android Default Notification Icon

To define a custom default notification icon, you need to create the images and deploy them to the <projectroot>/platforms/android/app/src/main/res/<drawable-DPI> folders. The easiest way to 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:

• mdpi: 24x24
• hdpi: 36x36
• xhdpi: 48x48
• xxhdpi: 72x72
• xxxhdpi: 96x96

Once you've created the images, you need to deploy them from your Cordova project to the native Android project. To do this, copy the drawable-DPI image directories into your Cordova project and add <resource-file> entries to the <platform name="android"> section of your config.xml, 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>

Android Large Notification Icon

The default notification icons above are monochrome, however you can additionally define a larger multi-coloured icon.

NOTE: FCM currently does not support large icons in system notifications displayed for notification messages received in the while the app is in the background (or not running). So the large icon will currently only be used if specified in data messages 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>

Android Custom Notification Icons

You can define additional sets of notification icons in the same manner as above. These can be specified in notification or data messages.

For example:

        <resource-file src="res/android/drawable-mdpi/my_icon.png" target="app/src/main/res/drawable-mdpi/my_icon.png" />
        <resource-file src="res/android/drawable-hdpi/my_icon.png" target="app/src/main/res/drawable-hdpi/my_icon.png" />
        <resource-file src="res/android/drawable-xhdpi/my_icon.png" target="app/src/main/res/drawable-xhdpi/my_icon.png" />
        <resource-file src="res/android/drawable-xxhdpi/my_icon.png" target="app/src/main/res/drawable-xxhdpi/my_icon.png" />
        <resource-file src="res/android/drawable-xxxhdpi/my_icon.png" target="app/src/main/res/drawable-xxxhdpi/my_icon.png" />
        <resource-file src="res/android/drawable-xxxhdpi/my_icon_large.png" target="app/src/main/res/drawable-xxxhdpi/my_icon_large.png" />

When sending an FCM notification message, you will then specify the icon name in the android.notification section, for example:

{
    "name": "my_notification",
    "notification": {
        "body": "Notification body",
        "title": "Notification title"
    },
    "android": {
        "notification": {
            "icon": "my_icon"
        }
    },
    "data": {
        "notification_foreground": "true"
    }
}

You can also reference these icons in data messages, for example:

{
    "name": "my_data",
    "data": {
        "notification_foreground": "true",
        "notification_body": "Notification body",
        "notification_title": "Notification title",
        "notification_android_icon": "my_icon"
    }
}

Android Notification Color

On Android Lollipop (5.0/API 21) and above you can set the default accent color for the notification by adding a color setting. This is defined as an ARGB colour 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"
    }
}

Android Notification Sound

You can specify custom sounds for notifications or play the device default notification sound.

Custom sound files must be in .mp3 format and deployed to the /res/raw directory in the Android project. To do this, you can add <resource-file> tags to your config.xml to deploy the files, for example:

<platform name="android">
    <resource-file src="res/android/raw/my_sound.mp3" target="app/src/main/res/raw/my_sound.mp3" />
</platform>

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"
        }
    }
}

Android 8.0 and above

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

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"
    }
}

• To play the default notification sound, set "sound": "default".
• To display a silent notification (no sound), omit the sound key from the message.

Android cloud message types

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.

iOS notifications

Notifications on iOS can be customised to specify the sound and badge number that's displayed when the notification arrives.

Notification settings are specified in the apns.payload.aps key of the notification message payload. For example:

{
    "name": "my_notification",
    "notification": {
        "body": "Notification body",
        "title": "Notification title"
    },
    "apns": {
        "payload": {
            "aps": {
                "sound": "default",
                "badge": 1,
                "content-available": 1
            }
        }
    }
}

iOS background notifications

If the notification message arrives while the app is in the background/not running, it will be displayed as a system notification.

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.

If the app is in the background or inactive when the notification message arrives, the message can be queued so that the next time the app is resumed from the background, the onMessageReceived callback is invoked with the notification payload 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 app is next launched/resumed from the background, any queued notification payloads will be sent to the onMessageReceived callback without the tap property, indicating the message was received without user interaction.

If you wish to attempt to immediately deliver the message payload to the onMessageReceived callback when the app is in the background or inactive (the default behaviour of this plugin prior to v18), you can set the FIREBASE_MESSAGING_IMMEDIATE_PAYLOAD_DELIVERY plugin variable to true at plugin install time:

cordova plugin add cordova-plugin-firebasex --variable FIREBASE_MESSAGING_IMMEDIATE_PAYLOAD_DELIVERY=true

However there is no guarantee that the message will be delivered successfully, since the Cordova application running in the Webview may not be in a state where it can receive the notification message.

iOS notification sound

You can specify custom sounds for notifications or play the device default notification sound.

Custom sound files must be in a supported audio format (see this Apple documentation for supported formats). For example to convert an .mp3 file to the supported .caf format run:

afconvert my_sound.mp3 my_sound.caf -d ima4 -f caff -v

Sound files must be deployed with the iOS application bundle. To do this, you can add <resource-file> tags to your config.xml to deploy the files, for example:

<platform name="ios">
    <resource-file src="res/ios/sound/my_sound.caf" />
</platform>

In a notification message, specify the sound key in the apns.payload.aps section, for example:

{
    "name": "my_notification",
    "notification": {
        "body": "Notification body",
        "title": "Notification title"
    },
    "apns": {
        "payload": {
            "aps": {
                "sound": "my_sound.caf"
            }
        }
    }
}

• To play the default notification sound, set "sound": "default".
• To display a silent notification (no sound), omit the sound key from the message.

In a data message, specify the notification_ios_sound key in the data section:

{
    "name": "my_data",
    "data": {
        "notification_foreground": "true",
        "notification_body": "Notification body",
        "notification_title": "Notification title",
        "notification_ios_sound": "my_sound.caf"
    }
}

iOS critical notifications

iOS offers the option to send critical push notifications. These kind of notifications appear even when your iPhone or iPad is in Do Not Disturb mode or silenced. Sending critical notifications requires a special entitlement that needs to be issued by Apple. Use the pugin setting IOS_ENABLE_CRITICAL_ALERTS_ENABLED=true to enable the critical push notifications capability. A user also needs to explicitly grant permission to receive critical alerts.

iOS badge number

In a notification message, specify the badge key in the apns.payload.aps section, for example:

{
    "name": "my_notification",
    "notification": {
        "body": "Notification body",
        "title": "Notification title"
    },
    "apns": {
        "payload": {
            "aps": {
                "badge": 1
            }
        }
    }
}

In a data message, specify the notification_ios_badge key in the data section:

{
    "name": "my_data",
    "data": {
        "notification_foreground": "true",
        "notification_body": "Notification body",
        "notification_title": "Notification title",
        "notification_ios_badge": 1
    }
}

iOS actionable notifications

Actionable notifications are supported on iOS:

To use them in your app you must do the following:

1. Add a 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.

2. Reference it as a resource file in your config.xml:

    <platform name="ios">
        ...
        <resource-file src="relative/path/to/pn-actions.json" />
    </platform>

3. Add a category entry to your FCM message payload which references one of your categories:

{
    "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:

• Actionable notifications are currently only available for iOS - not Android
• To reveal the notification action buttons, the user must drag downwards on the notification dialog
• Actionable notifications work with both foreground and background (system) notifications
• If your app is in the background/not running when the notification message arrives and a system notification is displayed, if the user chooses an action (instead of tapping the notification dialog body), your app will not be launched/foregrounded but onMessageReceived() will be invoked, enabling your app code to handle the user's action selection silently in the background.
• You can test out actionable notifications by building and running example project app and sending the ios_notification_actionable.json FCM message using the built-in FCM v1 HTTP API client which contains a category defined in the example pn-actions.json.

iOS notification settings button

Adding such a Button is possible with this Plugin. To enable this Feature, you need to pass true for requestWithProvidesAppNotificationSettings when you request the Permission.

You then need to subscribe to onOpenSettings and open your apps notification settings page.

Data messages

FCM data messages are sent as an arbitrary k/v structure and by default are passed to the app for it to handle them.

NOTE: FCM data messages cannot be sent from the Firebase Console - they can only be sent via the FCM APIs.

Data message notifications

This plugin enables a data message to be displayed as a system notification. To have the app display a notification when the data message arrives, you need to set the notification_foreground key in the data section. You can then set a notification_title and notification_body, for example:

{
    "name": "my_data",
    "data": {
        "notification_foreground": "true",
        "notification_body": "Notification body",
        "notification_title": "Notification title",
        "foo": "bar"
    }
}

Additional platform-specific notification options can be set using the additional keys below (which are only relevant if the notification_foreground key is set).

Note: foreground notification messages can also make use of these keys.

Android data message notifications

On Android:

• Data messages that arrive while your app is running in the foreground or running in the background will be immediately passed to the onMessageReceived() Javascript handler in the Webview.
• Data messages (not containing notification keys) that arrive while your app is not running will be passed to the onMessageReceived() Javascript handler when the app is next launched.
• Data messages containing notification keys that arrive while your app is running or not running will be displayed as a system notification.

The following Android-specific keys are supported and should be placed inside the data section:

• notification_android_id - Identifier used to replace existing notifications in the notification drawer
  • If not specified, each request creates a new notification.
  • If specified and a notification with the same tag is already being shown, the new notification replaces the existing one in the notification drawer.
• notification_android_body_html - If is passed, the body of a notification is processed as if it were html, you can use <b>, <i> or <s>
  • If not specified, the body of the notification will be processed as plain text.
• notification_android_icon - name of a custom notification icon in the drawable resources
  • if not specified, the plugin will use the default notification_icon if it exists; otherwise the default app icon will be displayed
  • if a large icon has been defined, it will also be displayed in the system notification.
• notification_android_color - the color accent to use for the small notification icon
  • if not specified, the default color accent will be used
• notification_android_image - Specifies the image notification
  • if not specified, the notification will not show any image
• notification_android_image_type - Specifies the image notification type
  • Possible values:
    • square - The image is displayed in the default format.
    • circle - This notification displays the image in circular format.
    • big_picture - Displays the image like square type, but the notification can be expanded and show the image in a big picture, example: https://developer.android.com/training/notify-user/expanded#image-style
  • Defaults to square if not specified.
• notification_android_channel_id - ID of the notification channel to use to display the notification
  • Only applies to Android 8.0 and above
  • If not specified, the default notification channel will be used.
    • You can override the default configuration for the default notification channel using setDefaultChannel.
  • You can create additional channels using createChannel.
• notification_android_priority - Specifies the notification priority
  • Possible values:
    • 2 - Highest notification priority for your application's most important items that require the user's prompt attention or input.
    • 1 - Higher notification priority for more important notifications or alerts.
    • 0 - Default notification priority.
    • -1 - Lower notification priority for items that are less important.
    • -2 - Lowest notification priority. These items might not be shown to the user except under special circumstances, such as detailed notification logs.
  • Defaults to 2 if not specified.
• notification_android_visibility - Specifies the notification visibility
  • Possible values:
    • 1 - Show this notification in its entirety on all lockscreens.
    • 0 - Show this notification on all lockscreens, but conceal sensitive or private information on secure lockscreens.
    • -1 - Do not reveal any part of this notification on a secure lockscreen.
  • Defaults to 1 if not specified.

The following keys only apply to Android 7 and below. On Android 8 and above they will be ignored - the notification_android_channel_id property should be used to specify a notification channel with equivalent settings.

• notification_android_sound - name of a sound resource to play as the notification sound
  • if not specified, no sound is played
  • default plays the default device notification sound
  • otherwise should be the name of an .mp3 file in the /res/raw directory, e.g. my_sound.mp3 => "sounds": "my_sound"
• notification_android_lights - color and pattern to use to blink the LED light
  • if not defined, LED will not blink
  • in the format ARGB, time_on_ms, time_off_ms where
    • ARGB is an ARGB color definition e.g. #ffff0000
    • time_on_ms is the time in milliseconds to turn the LED on for
    • time_off_ms is the time in milliseconds to turn the LED off for
  • e.g. "lights": "#ffff0000, 250, 250"
• notification_android_vibrate - pattern of vibrations to use when the message arrives
  • if not specified, device will not vibrate
  • an array of numbers specifying the time in milliseconds to vibrate
  • e.g. "vibrate": "500, 200, 500"

Example data message with Android notification keys:

{
    "name": "my_data_message",
    "data": {
        "notification_foreground": "true",
        "notification_body": "Notification body",
        "notification_title": "Notification title",
        "notification_android_channel_id": "my_channel",
        "notification_android_priority": "2",
        "notification_android_visibility": "1",
        "notification_android_color": "#ff0000",
        "notification_android_icon": "coffee",
        "notification_android_image": "https://example.com/avatar.jpg",
        "notification_android_image_type": "circle",
        "notification_android_sound": "my_sound",
        "notification_android_vibrate": "500, 200, 500",
        "notification_android_lights": "#ffff0000, 250, 250"
    }
}

iOS data message notifications

On iOS:

• Data messages that arrive while your app is running in the foreground or running in the background will be immediately passed to the onMessageReceived() Javascript handler in the Webview.
• Data messages that arrive while your app is not running will NOT be received by your app!

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
  • To play a custom sound, set the name of the sound file bundled with your app, e.g. "sound": "my_sound.caf" - see iOS notification sound for more info.
  • To play the default notification sound, set "sound": "default".
  • To display a silent notification (no sound), omit the sound key from the message.
• notification_ios_badge - Badge number to display on app icon on home screen.
• notification_ios_image_jpg - Specifies the jpg image notification, to use this you need to have configured the NotificationService - Tutorial to set it up
• notification_ios_image_png - Specifies the png image notification, to use this you need to have configured the NotificationService - Tutorial to set it up
• notification_ios_image_gif - Specifies the gif image notification, to use this you need to have configured the NotificationService - Tutorial to set it up

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,
        "notification_ios_image_png": "https://example.com/avatar.png"
    }
}

Custom FCM message handling

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.

Android

You'll need to add a native class which extends the FirebasePluginMessageReceiver abstract class and implements the onMessageReceived() and sendMessage() abstract methods.

iOS

You'll need to add a native class which extends the FirebasePluginMessageReceiver abstract class and implements the sendNotification() abstract method.

Example

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.

InApp Messaging

Engage active app users with contextual messages. The SDK component is included in the plugin but no explicit plugin API calls are required to use inapp messaging.

See the iOS and Android guides for how to send a test message.

Google Tag Manager

Download your container-config json file from Tag Manager and add a <resource-file> node in your config.xml.

Android

<platform name="android">
    <resource-file src="GTM-XXXXXXX.json" target="assets/containers/GTM-XXXXXXX.json" />
    ...

iOS

<platform name="ios">
    <resource-file src="GTM-YYYYYYY.json" />
    ...

Performance Monitoring

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 Performance Monitoring Gradle plugin

• The Firebase Performance Monitoring Gradle plugin for Android is required to enable automatic monitoring of network requests in Android apps.
• However, as outlined here, adding this Gradle plugin to your Android builds can significantly increase Android build times and memory usage.
• For this reason, the Gradle plugin is not added to your Android app builds by default.
• If you want to add it to make use of automatic network request monitoring on Android, set the ANDROID_FIREBASE_PERFORMANCE_MONITORING plugin variable flag at plugin install time:
  • --variable ANDROID_FIREBASE_PERFORMANCE_MONITORING=true
• If you choose to add it, the Gradle plugin currently requires Gradle v6.1.1 and Android Studio v4.0 or above.
• Note: on iOS when this plugin is installed, automatic network request monitoring takes place with requiring any extra configuration.

API

The list of available methods for this plugin is described below.

Notifications and data messages

The plugin is capable of receiving push notifications and FCM data messages.

See Cloud messaging section for more.

getToken

Get the current FCM token. Null if the token has not been allocated yet by the Firebase SDK.

Parameters:

• {function} success - callback function which will be passed the {string} token as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

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.

getId

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:

• {function} success - callback function which will be passed the {string} ID as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

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.

onTokenRefresh

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:

• {function} success - callback function which will be passed the {string} token as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.onTokenRefresh(
    function (fcmToken) {
        console.log(fcmToken);
    },
    function (error) {
        console.error(error);
    }
);

getAPNSToken

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:

• {function} success - callback function which will be passed the {string} APNS token as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.getAPNSToken(
    function (apnsToken) {
        console.log(apnsToken);
    },
    function (error) {
        console.error(error);
    }
);

onApnsTokenReceived

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:

• {function} success - callback function which will be passed the {string} token as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.onApnsTokenReceived(
    function (apnsToken) {
        console.log(apnsToken);
    },
    function (error) {
        console.error(error);
    }
);

onOpenSettings

iOS only Registers a callback function to invoke when the AppNotificationSettingsButton is tapped by the user

Parameters:

• {function} success - callback function which will be invoked without any argument
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.onOpenSettings(
    function () {
        console.log("Redirect to App Notification Settings Page here");
    },
    function (error) {
        console.error(error);
    }
);

onMessageReceived

Registers a callback function to invoke when:

• a notification or data message is received by the app
• a system notification is tapped by the user

Parameters:

• {function} success - callback function which will be passed the {object} message as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

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 message
• tap=foreground|background - set if the call to onMessageReceived() was initiated by user tapping on a system notification.
  • indicates if the system notification was tapped while the app was in the foreground or background.
  • not set if no system notification was tapped (i.e. message was received directly from FCM rather than via a user tap on a system notification).

Notification message flow:

1. App is in foreground: a. By default, when a notification message arrives the app receives the notification message payload in the onMessageReceived JavaScript callback without any system notification on the device itself. b. If the data section contains the notification_foreground key, the plugin will display a system notification while in the foreground.
2. App is in background: a. User receives the notification message as a system notification in the device notification bar b. User taps the system notification which launches the app b. User receives the notification message payload in the onMessageReceived JavaScript callback

Data message flow:

1. App is in foreground: a. By default, when a data message arrives the app receives the data message payload in the onMessageReceived JavaScript callback without any system notification on the device itself. b. If the data section contains the notification_foreground key, the plugin will display a system notification while in the foreground.
2. App is in background: a. The app receives the data message in the onMessageReceived JavaScript callback while in the background b. If the data message contains the data message notification keys, the plugin will display a system notification for the data message while in the background.

grantPermission

Grant run-time permission to receive push notifications (will trigger user permission prompt). iOS & Android 13+ (Android <= 12 will always return true).

On Android, the POST_NOTIFICATIONS permission must be added to the AndroidManifest.xml file by inserting the following into your config.xml file:

<config-file target="AndroidManifest.xml" parent="/*">
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
</config-file>

Note, in addition to removing and re-adding the android platform, you may need to add the following attribute to <widget> in your config.xml file to avoid a parse error when building: xmlns:android="http://schemas.android.com/apk/res/android"

Parameters:

• {function} success - callback function which will be passed the {boolean} permission result as an argument
• {function} error - callback function which will be passed a {string} error message as an argument
• {boolean} requestWithProvidesAppNotificationSettings - (iOS12+ only) indicates if app provides AppNotificationSettingsButton

FirebasePlugin.grantPermission(function (hasPermission) {
    console.log(
        "Notifications permission was " + (hasPermission ? "granted" : "denied")
    );
});

grantCriticalPermission

Grant critical permission to receive critical push notifications (will trigger additional prompt). iOS 12.0+ only (Android will always return true).

Parameters:

• {function} success - callback function which will be passed the {boolean} permission result as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

Critical push notifications require a special entitlement that needs to be issued by Apple.

FirebasePlugin.grantCriticalPermission(function (hasPermission) {
    console.log(
        "Critical notifications permission was " +
            (hasPermission ? "granted" : "denied")
    );
});

hasPermission

Check permission to receive push notifications and return the result to a callback function as boolean. On iOS, returns true if runtime permission for remote notifications is granted and enabled in Settings. On Android, returns true if global remote notifications are enabled in the device settings and (on Android 13+) runtime permission for remote notifications is granted.

Parameters:

• {function} success - callback function which will be passed the {boolean} permission result as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.hasPermission(function (hasPermission) {
    console.log("Permission is " + (hasPermission ? "granted" : "denied"));
});

hasCriticalPermission

Check permission to receive critical push notifications and return the result to a callback function as boolean. iOS 12.0+ only (Android will always return true).

Critical push notifications require a special entitlement that needs to be issued by Apple.

Parameters:

• {function} success - callback function which will be passed the {boolean} permission result as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.hasCriticalPermission(function (hasPermission) {
    console.log(
        "Permission to send critical push notifications is " +
            (hasPermission ? "granted" : "denied")
    );
});

unregister

Unregisters from Firebase Cloud Messaging by deleting the current FCM 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, be sure to disable autoinit using setAutoInitEnabled() before calling unregister().

You can disable autoinit on first run and therefore prevent an FCM token being allocated by default (allowing user opt-in) by setting the FIREBASE_FCM_AUTOINIT_ENABLED plugin variable at plugin installation time:

cordova plugin add cordova-plugin-firebasex --variable FIREBASE_FCM_AUTOINIT_ENABLED=false

Parameters: None

FirebasePlugin.unregister();

isAutoInitEnabled

Indicates whether autoinit is currently enabled. If so, new FCM tokens will be automatically generated.

Parameters:

• {function} success - callback function which will be passed the {boolean} result as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.isAutoInitEnabled(function (enabled) {
    console.log("Auto init is " + (enabled ? "enabled" : "disabled"));
});

setAutoInitEnabled

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:

• {boolean} enabled - set true to enable, false to disable
• {function} success - callback function to call on successful execution of operation.
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.setAutoInitEnabled(false, function () {
    console.log("Auto init has been disabled ");
    FirebasePlugin.unregister();
});

setBadgeNumber

iOS only. Set a number on the icon badge:

Parameters:

• {integer} badgeNumber - number to set for the app badge

FirebasePlugin.setBadgeNumber(3);

Set 0 to clear the badge

FirebasePlugin.setBadgeNumber(0);

Note: this function is no longer available on Android (see #124)

getBadgeNumber

iOS only. Get icon badge number:

Parameters:

• {function} success - callback function which will be passed the {integer} current badge number as an argument

FirebasePlugin.getBadgeNumber(function (n) {
    console.log(n);
});

Note: this function is no longer available on Android (see #124)

clearAllNotifications

Clear all pending notifications from the drawer:

Parameters: None

FirebasePlugin.clearAllNotifications();

subscribe

Subscribe to a topic.

Topic messaging allows you to send a message to multiple devices that have opted in to a particular topic.

Parameters:

• {string} topicName - name of topic to subscribe to
• {function} success - callback function which will be call on successful subscription
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.subscribe(
    "latest_news",
    function () {
        console.log("Subscribed to topic");
    },
    function (error) {
        console.error("Error subscribing to topic: " + error);
    }
);

unsubscribe

Unsubscribe from a topic.

This will stop you receiving messages for that topic

Parameters:

• {string} topicName - name of topic to unsubscribe from
• {function} success - callback function which will be call on successful unsubscription
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.unsubscribe(
    "latest_news",
    function () {
        console.log("Unsubscribed from topic");
    },
    function (error) {
        console.error("Error unsubscribing from topic: " + error);
    }
);

createChannel

Android 8+ only. Creates a custom channel to be used by notification messages which have the channel property set in the message payload to the id of the created channel:

• For background (system) notifications: android.notification.channel_id
• For foreground/data notifications: data.notification_android_channel_id

For each channel you may set the sound to be played, the color of the phone LED (if supported by the device), whether to vibrate and set vibration pattern (if supported by the device), importance and visibility. Channels should be created as soon as possible (on program start) so notifications can work as expected. A default channel is created by the plugin at app startup; the properties of this can be overridden see setDefaultChannel

Calling on Android 7 or below or another platform will have no effect.

Note: Each time you want to play a different sound, you need to create a new channel with a new unique ID - do not re-use the same channel ID even if you have called deleteChannel() (see this comment).

Parameters:

• {object} - channel configuration object (see below for object keys/values)
• {function} success - callback function which will be call on successful channel creation
• {function} error - callback function which will be passed a {string} error message as an argument

// 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,

    // Optionally specify the usage type of the notification. Defaults to USAGE_NOTIFICATION_RINGTONE ( =6)
    // For a list of all possible usages, see https://developer.android.com/reference/android/media/AudioAttributes.Builder#setUsage(int)

    usage: 6,
    // Optionally specify the stream type of the notification channel.
    // For a list of all possible values, see https://developer.android.com/reference/android/media/AudioAttributes.Builder#setLegacyStreamType(int)
    streamType: 5,
};

// 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.

setDefaultChannel

Android 8+ only. Overrides the properties for the default channel. The default channel is used if no other channel exists or is specified in the notification. Any options not specified will not be overridden. Should be called as soon as possible (on app start) so default notifications will work as expected. Calling on Android 7 or below or another platform will have no effect.

Parameters:

• {object} - channel configuration object
• {function} success - callback function which will be call on successfully setting default channel
• {function} error - callback function which will be passed a {string} error message as an argument

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);
    }
);

Default Android Channel Properties

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
}

deleteChannel

Android 8+ only. Removes a previously defined channel. Calling on Android 7 or below or another platform will have no effect.

Parameters:

• {string} - id of channel to delete
• {function} success - callback function which will be call on successfully deleting channel
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.deleteChannel(
    "my_channel_id",
    function () {
        console.log("Channel deleted");
    },
    function (error) {
        console.log("Delete channel error: " + error);
    }
);

listChannels

Android 8+ only. Gets a list of all channels. Calling on Android 7 or below or another platform will have no effect.

Parameters:

• {function} success - callback function which will be passed the {array} of channel objects as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.listChannels(
    function (channels) {
        if (typeof channels == "undefined") return;

        for (var i = 0; i < channels.length; i++) {
            console.log(
                "ID: " + channels[i].id + ", Name: " + channels[i].name
            );
        }
    },
    function (error) {
        alert("List channels error: " + error);
    }
);

Analytics

Firebase Analytics enables you to log events in order to track use and behaviour of your apps.

By default, Firebase does not store fine-grain analytics data - only a sample is taken and detailed event data is then discarded. The Firebase Analytics console is designed to give you a coarse overview of analytics data.

If you want to analyse detailed, event-level analytics you should consider exporting Firebase Analytics data to BigQuery. 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.

setAnalyticsCollectionEnabled

Manually enable/disable analytics data collection, e.g. if disabled on app startup.

Parameters:

• {boolean} setEnabled - whether to enable or disable analytics data collection

FirebasePlugin.setAnalyticsCollectionEnabled(true); // Enables analytics data collection

FirebasePlugin.setAnalyticsCollectionEnabled(false); // Disables analytics data collection

isAnalyticsCollectionEnabled

Indicates whether analytics data collection is enabled.

Notes:

• This value applies both to the current app session and subsequent app sessions until such time as it is changed.
• It returns the value set by setAnalyticsCollectionEnabled().
• If automatic data collection was not disabled on app startup, this will always return true.

Parameters:

• {function} success - callback function which will be invoked on success. Will be passed a {boolean} indicating if the setting is enabled.
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

FirebasePlugin.isAnalyticsCollectionEnabled(
    function (enabled) {
        console.log(
            "Analytics data collection is " + (enabled ? "enabled" : "disabled")
        );
    },
    function (error) {
        console.error(
            "Error getting Analytics data collection setting: " + error
        );
    }
);

AnalyticsConsentMode

Constants defining the mode of consent to set:

• {string} AnalyticsConsentMode.ANALYTICS_STORAGE - consent for analytics data storage
• {string} AnalyticsConsentMode.AD_STORAGE - consent for ad storage
• {string} AnalyticsConsentMode.AD_USER_DATA - consent for ad user data
• {string} AnalyticsConsentMode.AD_PERSONALIZATION `- consent for ad personalization

AnalyticsConsentStatus

Constants defining the status of consent to set:

• {string} AnalyticsConsentStatus.GRANTED - consent granted
• {string} AnalyticsConsentStatus.DENIED - consent denied

setAnalyticsConsentMode

Sets the user's consent mode status for various types of data collection in the application. This includes consent for analytics data storage, ad storage, ad personalization, and ad user data. The consent status can be set to 'GRANTED' or 'DENIED'. Read more here

Parameters:

• {object} consent - map of the consent modes as AnalyticsConsentMode and their status as AnalyticsConsentStatus

var consents = {};
consents[FirebasePlugin.AnalyticsConsentMode.ANALYTICS_STORAGE] = FirebasePlugin.AnalyticsConsentStatus.GRANTED;
consents[FirebasePlugin.AnalyticsConsentMode.AD_STORAGE] = FirebasePlugin.AnalyticsConsentStatus.GRANTED;
consents[FirebasePlugin.AnalyticsConsentMode.AD_USER_DATA] = FirebasePlugin.AnalyticsConsentStatus.GRANTED;
consents[FirebasePlugin.AnalyticsConsentMode.AD_PERSONALIZATION] = FirebasePlugin.AnalyticsConsentStatus.DENIED;

FirebasePlugin.setAnalyticsConsentMode(consents, function() {
    console.log("Consent mode set");
}, function(error) {
    console.error("Error setting consent mode: " + error);
});

logEvent

Log an event using Analytics:

Parameters:

• {string} eventName - name of event to log to Firebase Analytics
  • Limit of 40 characters.
  • Dots are not allowed in eventName.
• {object} eventProperties - key/value object of custom event properties.
  • This must be a flat (non-nested) object.
  • The value must be a primitive type such as string/number/etc. (not a complex object such as array or nested object).
  • Limit of 40 characters for parameter name and 100 characters for parameter value.

FirebasePlugin.logEvent("select_content", {
    content_type: "page_view",
    item_id: "home",
});

setScreenName

Set the name of the current screen in Analytics:

Parameters:

• {string} screenName - name of screen to log to Firebase Analytics

FirebasePlugin.setScreenName("Home");

setUserId

Set a user id for use in Analytics:

Parameters:

• {string} userName - name of user to set in Firebase Analytics

FirebasePlugin.setUserId("user_id");

setUserProperty

Set a user property for use in Analytics:

Parameters:

• {string} name - name of user property to set in Firebase Analytics
• {string} value - value of user property to set in Firebase Analytics

FirebasePlugin.setUserProperty("name", "value");

initiateOnDeviceConversionMeasurement

Initiates on-device conversion measurement using either user's email address or phone number. iOS only.

Parameters:

• {object} userIdentifier - user identifier as either emailAddress or phoneNumber key
• {function} success - callback function which will be invoked on success. Will be passed a {boolean} indicating if the setting is enabled.
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

FirebasePlugin.initiateOnDeviceConversionMeasurement(
    { emailAddress: "me@here.com" },
    function () {
        console.log("On device conversion measurement initiated");
    },
    function (error) {
        console.error(
            "Error initiating on device conversion measurement: " + error
        );
    }
);

Crashlytics

By default this plugin will ensure fatal native crashes in your apps are reported to Firebase via the Firebase (not Fabric) Crashlytics SDK.

setCrashlyticsCollectionEnabled

Manually enable/disable Crashlytics data collection, e.g. if disabled on app startup.

Parameters:

• {boolean} setEnabled - whether to enable or disable Crashlytics data collection.
• {function} success - (optional) callback function which will be invoked on success
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

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
        );
    }
);

didCrashOnPreviousExecution

Checks whether the app crashed on its previous run.

Parameters:

• {function} success - callback function which will be invoked on success. Will be passed a {boolean} indicating whether the app crashed on its previous run.
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

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}`);
});

isCrashlyticsCollectionEnabled

Indicates whether Crashlytics collection setting is currently enabled.

Parameters:

• {function} success - callback function which will be invoked on success. Will be passed a {boolean} indicating if the setting is enabled.
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

FirebasePlugin.isCrashlyticsCollectionEnabled(
    function (enabled) {
        console.log(
            "Crashlytics data collection is " +
                (enabled ? "enabled" : "disabled")
        );
    },
    function (error) {
        console.error(
            "Error getting Crashlytics data collection setting: " + error
        );
    }
);

setCrashlyticsUserId

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:

• {string} userId - User ID to associate with Crashlytics reports

FirebasePlugin.setCrashlyticsUserId("user_id");

sendCrash

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();

setCrashlyticsCustomKey

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:

• {string} key - A unique key
• {string | number | boolean} value - A value to be associated with the given key
• {function} success - (optional) callback function which will be invoked on success
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

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();

logMessage

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:

• {string} message - message to associate with next native crash event

FirebasePlugin.logMessage("about to send a crash for testing!");
FirebasePlugin.sendCrash();

logError

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. Note that logged errors will only be sent to the Crashlytics server on the next full app restart. Also logs the error message to the native device console.

Parameters:

• {string} errorMessage - non-fatal error message to log to Crashlytics
• {object} stackTrace - (optional) a stack trace generated by stacktrace.js
• {function} success - (optional) callback function which will be invoked on success
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

// 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

Authentication

isUserSignedIn

Checks if there is a current Firebase user signed into the app.

Parameters:

• {function} success - callback function to pass {boolean} result to as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

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);
    }
);

signOutUser

Signs current Firebase user out of the app.

Parameters:

• {function} success - callback function to pass {boolean} result to as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.signOutUser(
    function () {
        console.log("User signed out");
    },
    function (error) {
        console.error("Failed to sign out user: " + error);
    }
);

getCurrentUser

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:

• {function} success - callback function to pass user {object} to as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

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);
        console.log("creationTime", user.creationTimestamp);
        console.log("lastSignInTime", user.lastSignInTimestamp);

        for (var i = 0; i < user.providers.length; i++) {
            console.log("providerId", user.providers[i].providerId);
            console.log("uid", user.providers[i].uid);
            console.log("displayName", user.providers[i].displayName);
            console.log("email", user.providers[i].email);
            console.log("phoneNumber", user.providers[i].phoneNumber);
            console.log("photoUrl", user.providers[i].photoUrl);
        }
    },
    function (error) {
        console.error("Failed to get current user data: " + error);
    }
);

reloadCurrentUser

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:

• {function} success - callback function to pass user {object} to as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

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);
    }
);

updateUserProfile

Updates the display name and/or photo URL of the current Firebase user signed into the app.

Parameters:

• {object} profile - new profile details:
  • {string} name - display name of user
  • {string} photoUri - URL of user profile photo
• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument

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);
    }
);

updateUserEmail

Updates/sets the email address of the current Firebase user signed in to the app.

Parameters:

• {string} email - email address of user to set as current
• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.updateUserEmail(
    "user@somewhere.com",
    function () {
        console.log("User email successfully updated");
    },
    function (error) {
        console.error("Failed to update user email: " + error);
    }
);

sendUserEmailVerification

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:

• {object} actionCodeSettings - action code settings based on Passing State in Email Actions Parameters :
  • {boolean} handleCodeInApp - Whether the email action link will be opened in a mobile app or a web link first
  • {string} url - Continue URL after email has been verified
  • {string} dynamicLinkDomain - Sets the dynamic link domain to use for the current link if it is to be opened using Firebase Dynamic Links
  • {string} iosBundleId - Sets the iOS bundle ID. This will try to open the link in an iOS app if it is installed
  • {string} androidPackageName - Sets the Android package name. This will try to open the link in an android app if it is installed
  • {boolean} installIfNotAvailable - Install if the provided app package name is not already installed on the users device (Android only)
  • {string} minimumVersion - minimum app version required (Android Only)
• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.sendUserEmailVerification(
    {
        handleCodeInApp: true,
        url: "http://www.example.com",
        dynamicLinkDomain: "example.page.link",
        iosBundleId: "com.example.ios",
        androidPackageName: "com.example.android",
        installIfNotAvailable: true,
        minimumVersion: "12",
    },
    function () {
        console.log("User verification email successfully sent");
    },
    function (error) {
        console.error("Failed to send user verification email: " + error);
    }
);

verifyBeforeUpdateEmail

First verifies the user's identity, then set/supdates the email address of the current Firebase user signed in to the app.

• This is required when a user with multi-factor authentication enabled on their account wishes to change their registered email address.
  • updateUserEmail cannot be used and will result in an error.
• See the Firebase documentation regarding updating the email address of a user with multi-factor authentication enabled.

Parameters:

• {string} email - email address of user to set as current
• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.verifyBeforeUpdateEmail(
    "user@somewhere.com",
    function () {
        console.log("User verified and email successfully updated");
    },
    function (error) {
        console.error("Failed to verify user/update user email: " + error);
    }
);

updateUserPassword

Updates/sets the account password for the current Firebase user signed into the app.

Parameters:

• {string} password - user-defined password
• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.updateUserPassword(
    "mypassword",
    function () {
        console.log("User password successfully updated");
    },
    function (error) {
        console.error("Failed to update user password: " + error);
    }
);

sendUserPasswordResetEmail

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:

• {string} email - email address of user
• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument

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);
    }
);

deleteUser

Deletes the account of the current Firebase user signed into the app.

Parameters:

• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.deleteUser(
    function () {
        console.log("User account deleted");
    },
    function (error) {
        console.error("Failed to delete current user account: " + error);
    }
);

createUserWithEmailAndPassword

Creates a new email/password-based user account. If account creation is successful, user will be automatically signed in.

Parameters:

• {string} email - user email address. It is the responsibility of the app to ensure this is a valid email address.
• {string} password - user password. It is the responsibility of the app to ensure the password is suitable.
• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument.
  • If the error is due to the user account requiring multi-factor authentication, a second {array} argument will be passed containing a list of enrolled factors.
    • A factor should be selected and used for second factor verification - see verifySecondAuthFactor for more on this.

Example usage:

FirebasePlugin.createUserWithEmailAndPassword(
    email,
    password,
    function () {
        console.log("Successfully created email/password-based user account");
        // User is now signed in
    },
    function (error, secondFactors) {
        if (
            error === "Second factor required" &&
            typeof secondFactors !== "undefined"
        ) {
            handleSecondFactorAuthentation(secondFactors); // you need to implement this
        } else {
            console.error(
                "Failed to create email/password-based user account",
                error
            );
        }
    }
);

signInUserWithEmailAndPassword

Signs in to an email/password-based user account.

Parameters:

• {string} email - user email address
• {string} password - user password
• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument
  • If the error is due to the user account requiring multi-factor authentication, a second {array} argument will be passed containing a list of enrolled factors. - A factor should be selected and used for second factor verification - see verifySecondAuthFactor for more on this.

Example usage:

FirebasePlugin.signInUserWithEmailAndPassword(
    email,
    password,
    function () {
        console.log("Successfully signed in");
        // User is now signed in
    },
    function (error, secondFactors) {
        if (
            error === "Second factor required" &&
            typeof secondFactors !== "undefined"
        ) {
            handleSecondFactorAuthentation(secondFactors); // you need to implement this
        } else {
            console.error("Failed to sign in", error);
        }
    }
);

signInUserWithCustomToken

Signs in user with custom token.

Parameters:

• {string} customToken - the custom token
• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument
  • If the error is due to the user account requiring multi-factor authentication, a second {array} argument will be passed containing a list of enrolled factors. - A factor should be selected and used for second factor verification - see verifySecondAuthFactor for more on this.

Example usage:

FirebasePlugin.signInUserWithCustomToken(
    customToken,
    function () {
        console.log("Successfully signed in");
        // User is now signed in
    },
    function (error, secondFactors) {
        if (
            error === "Second factor required" &&
            typeof secondFactors !== "undefined"
        ) {
            handleSecondFactorAuthentation(secondFactors); // you need to implement this
        } else {
            console.error("Failed to sign in", error);
        }
    }
);

signInUserAnonymously

Signs in user anonymously.

Parameters:

• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument

Example usage:

FirebasePlugin.signInUserAnonymously(
    function () {
        console.log("Successfully signed in");
        // User is now signed in
    },
    function (error) {
        console.error("Failed to sign in", error);
    }
);

verifyPhoneNumber

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:

• Some Android devices support "instant verification" where the phone number can be instantly verified without sending or receiving an SMS.
  • In this case, the user doesn't need to do anything in order for you to sign them in and you don't need to provide any additional credentials in order to sign the user in or link the user account to an existing Firebase user account.
• Some Android devices support "auto-retrieval" where Google Play services is able to detect the incoming verification SMS and perform verification with no user action required.
  • As above, the user doesn't need to do anything in order for you to sign them in.
• For other Android devices and all iOS devices, the user must manually enter the verification code received in the SMS into your app.
  • This code be used, along with the accompanying verification ID, to sign the user in or link phone number to an existing Firebase user account.

Parameters:

• {function} success - callback function to pass {object} credentials to as an argument
• {function} error - callback function which will be passed a {string} error message as an argument
• {string} phoneNumber - phone number to verify
• {object} opts - (optional) parameters
  • {integer} timeOutDuration - (Android only) time to wait in seconds before timing out. Defaults to 30 seconds if not specified.
  • {boolean} requireSmsValidation - (Android only) whether to always require SMS validation on Android even if instant verification is available. Defaults to false if not specified.
  • {string} fakeVerificationCode - (Android only) to test instant verification on Android, specify a fake verification code to return for whitelisted phone numbers.
    • See Firebase SDK Phone Auth Android Integration Testing for more info.

The success callback will be passed a credential object with the following possible properties:

• {boolean} instantVerification - 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.
• {string} id - the identifier of a native credential object which can be used for signing in the user. Will only be present if instantVerification is true.
• {string} verificationId - the verification ID to be passed along with the verification code sent via SMS to sign the user in. Will only be present if 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: timeOutDuration,
        requireSmsValidation: false,
        fakeVerificationCode: fakeVerificationCode,
    }
);

function signInWithCredential(credential) {
    FirebasePlugin.signInWithCredential(
        credential,
        function () {
            console.log("Successfully signed in");
        },
        function (error) {
            console.error("Failed to sign in", error);
        }
    );
}

Android

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.

iOS

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:

• setup your iOS app for push notifications
• Verify that push notifications are arriving on your physical device
• Upload your APNs auth key to the Firebase console.

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.

enrollSecondAuthFactor

Enrolls a user-specified phone number as a second factor for multi-factor authentication (MFA).

• As with verifyPhoneNumber, this may require the user to manually input the verification code received in an SMS message.
  • In this case, once the user has entered the code, enrollSecondAuthFactor will need to be called again with the credential option used to specified the code and verification id.
• This function involves a similar verification flow to verifyPhoneNumber and therefore has the same pre-requisites and requirements.
• See the Firebase MFA documentation for Android and iOS for more information on MFA-specific setup requirements.
• Calling when no user is signed in will result in error callback being invoked.

Parameters:

• {function} success - callback function to invoke either upon:
  • successful enrollment: will be passed true as an argument
  • user-entered verification code required: will be passed a credential object with a verification id.
• {function} error - callback function which will be passed a {string} error message as an argument
• {string} phoneNumber - phone number to enroll
• {object} opts - (optional) parameters
  • {string} displayName - display name for second factor.
    • Used when a user has multiple second factor phone numbers enrolled and asking them which to use since the full phone number is masked.
    • If not specified, defaults to the masked phone number.
  • {object} credential - if manual entry of the verification code in an SMS is required, the credential object will be passed to the success function. The user-entered code should be appended to this object as the code property then this function re-invoked with the credential specified in the opts argument.
  • {integer} timeOutDuration - (Android only) time to wait in seconds before timing out. Defaults to 30 seconds if not specified.
  • {boolean} requireSmsValidation - (Android only) whether to always require SMS validation on Android even if instant verification is available. Defaults to false if not specified.
  • {string} fakeVerificationCode - (Android only) to test instant verification on Android, specify a fake verification code to return for whitelisted phone numbers.
    • See Firebase SDK Phone Auth Android Integration Testing for more info.

Example usage:

var phoneNumber = "+441234567890";
var timeOutDuration = 60;
var fakeVerificationCode = "123456";
var displayName = "Work phone";
var credential;

function enrollSecondAuthFactor() {
    FirebasePlugin.enrollSecondAuthFactor(
        function (result) {
            if (typeof result === "object") {
                // User must enter SMS verification code manually
                credential = result;
                promptUserToInputCode() // you need to implement this
                    .then(function (userEnteredCode) {
                        credential.code = userEnteredCode; // set the user-entered verification code on the credential object
                        enrollSecondAuthFactor(); // re-invoke the function with the credential
                    });
            } else {
                console.log("Second factor successfully enrolled");
            }
        },
        function (error) {
            console.error(
                "Failed to enroll second factor: " + JSON.stringify(error)
            );
        },
        phoneNumber,
        {
            displayName: displayName,
            credential: credential,
            timeOutDuration: timeOutDuration,
            requireSmsValidation: false,
            fakeVerificationCode: fakeVerificationCode,
        }
    );
}
enrollSecondAuthFactor();

verifySecondAuthFactor

Verifies a second factor phone number for multi-factor authentication (MFA).

• If a user has MFA enrolled on their account, when they try to perform an authentication operation, such as sign-in using one of the first factor methods (e.g. signInUserWithEmailAndPassword), the error callback of that function will be invoked.
  • The first argument passed to the error callback will be the error message: "Second factor required"
  • A second argument will be passed containing the list of (one or more) enrolled second factors for that user; each factor in the list will be an object with the following properties:
    • {integer} index - index of the factor in the list - specify this as selectedIndex to select this factor.
    • {string} displayName - name of factor specified by the user when this factor was enrolled.
      • If no name was specified during enrollment, defaults to the masked phone number.
    • {string} phoneNumber - phone number for this factor.
• The app should then call this function, specifying the selectedIndex of the second factor in the params argument.
  • If there is more than one second factor enrolled, the app should ask the user to select which one to use and specify the index of this as the selectedIndex
  • If there is only one, the selectedIndex should be specified as 0.
• As with verifyPhoneNumber, this may require the user to manually input the verification code received in an SMS message.
  • In this case, once the user has entered the code, enrollSecondAuthFactor will need to be called again with the credential option used to specified the code and verification id.
• This function involves a similar verification flow to verifyPhoneNumber and therefore has the same pre-requisites and requirements.
• See the Firebase MFA documentation for Android and iOS for more information on MFA-specific setup requirements.

Parameters:

• {function} success - callback function to invoke either upon:
  • successful verification : will be passed true as an argument
  • user-entered verification code required: will be passed a credential object with a verification id.
• {function} error - callback function which will be passed a {string} error message as an argument
• {object} params - conditionally required parameters - either:
  • {integer} selectedIndex - index of selected second factor phone number to use for verification.
  • {object} credential - if manual entry of the verification code in an SMS is required, the credential object will be passed to the success function. The user-entered code should be appended to this object as the code property then this function
• {object} opts - (optional Android only) parameters re-invoked with the credential specified in the opts argument.
  • {integer} timeOutDuration - time to wait in seconds before timing out. Defaults to 30 seconds if not specified.
  • {boolean} requireSmsValidation - whether to always require SMS validation on Android even if instant verification is available. Defaults to false if not specified.
  • {string} fakeVerificationCode - to test instant verification on Android, specify a fake verification code to return for whitelisted phone numbers.
    • See Firebase SDK Phone Auth Android Integration Testing for more info.
  • {string} phoneNumber - phone number to use for fake instant verification - required if fakeVerificationCode is specified

Example usage:

var selectedIndex, credential;

function verifySecondAuthFactor() {
    FirebasePlugin.verifySecondAuthFactor(
        function (result) {
            if (typeof result === "object") {
                // User must enter SMS verification code manually
                credential = result;
                promptUserToInputCode() // you need to implement this
                    .then(function (userEnteredCode) {
                        credential.code = userEnteredCode; // set the user-entered verification code on the credential object
                        verifySecondAuthFactor(); // re-invoke the function with the credential
                    });
            } else {
                console.log("Second factor successfully enrolled");
            }
        },
        function (error) {
            console.error(
                "Failed to enroll second factor: " + JSON.stringify(error)
            );
        },
        {
            selectedIndex: selectedIndex,
            credential: credential,
        }
    );
}

FirebasePlugin.signInWithCredential(
    credential,
    function () {
        console.log("Successfully signed in");
    },
    function (error, secondFactors) {
        if (
            error === "Second factor required" &&
            typeof secondFactors !== "undefined"
        ) {
            if (secondFactors.length === 1) {
                // Only 1 enrolled second factor so select and use it
                selectedIndex = 0;
                verifySecondAuthFactor();
            } else {
                // Multiple second factors enrolled so ask user to choose which to use
                promptUserToSelectFactor(secondFactors) // you need to implement this
                    .then(function (_selectedIndex) {
                        selectedIndex = _selectedIndex;
                        verifySecondAuthFactor();
                    });
            }
        } else {
            console.error("Failed to sign in", error);
        }
    }
);

listEnrolledSecondAuthFactors

Lists the second factors the current user has enrolled for multi-factor authentication (MFA).

• Calling when no user is signed in will result in error callback being invoked.

Parameters:

• {function} success - callback function to invoke upon successfully retrieving second factors. Will be passed an {array} of second factor {object} with properties:

  • {integer} index - index of the factor in the list
  • {string} displayName - name of factor specified by the user when this factor was enrolled.
    • If no name was specified during enrollment, defaults to the masked phone number.
  • {string} phoneNumber - (Android only) enrolled phone number for this factor.
    • On iOS, this is not available when listing enrolled factors.

• {function} error - callback function which will be passed a {string} error message as an argument

Example usage:

FirebasePlugin.listEnrolledSecondAuthFactors(
    function (secondFactors) {
        if (secondFactors.length > 0) {
            for (var secondFactor of secondFactors) {
                console.log(
                    `${secondFactor.index}: ${secondFactor.displayName}${
                        secondFactor.phoneNumber
                            ? " (" + secondFactor.phoneNumber + ")"
                            : ""
                    }`
                );
            }
        } else {
            console.log("No second factors are enrolled");
        }
    },
    function (error) {
        console.error(
            "Failed to list second factors: " + JSON.stringify(error)
        );
    }
);

unenrollSecondAuthFactor

Unenrolls (removes) an enrolled second factor that the current user has enrolled for multi-factor authentication (MFA).

• Calling when no user is signed in will result in error callback being invoked.

Parameters:

• {function} success - callback function to invoke upon success
• {function} error - callback function which will be passed a {string} error message as an argument
• {number} selectedIndex - Index of the second factor to unenroll (obtained using listEnrolledSecondAuthFactors)

Example usage:

function unenrollSecondAuthFactor() {
    FirebasePlugin.listEnrolledSecondAuthFactors(
        function (secondFactors) {
            askUserToSelectSecondFactorToUnenroll(secondFactors) // you implement this
                .then(function (selectedIndex) {
                    FirebasePlugin.unenrollSecondAuthFactor(
                        function () {
                            console.log(
                                "Successfully unenrolled selected second factor"
                            );
                        },
                        function (error) {
                            console.error(
                                "Failed to unenroll second factor: " +
                                    JSON.stringify(error)
                            );
                        },
                        selectedIndex
                    );
                });
        },
        function (error) {
            console.error(
                "Failed to list second factors: " + JSON.stringify(error)
            );
        }
    );
}

setLanguageCode

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:

• {string} lang - language to change, ex: 'fr' for french

Example usage:

FirebasePlugin.setLanguageCode("fr"); // will switch to french

authenticateUserWithEmailAndPassword

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:

• {string} email - user email address
• {string} password - user password
• {function} success - callback function to pass {object} credentials to as an argument. The credential object has the following properties:
  • {string} id - the identifier of a native credential object which can be used for signing in the user.
• {function} error - callback function which will be passed a {string} error message as an argument
  • If the error is due to the user account requiring multi-factor authentication, a second {array} argument will be passed containing a list of enrolled factors.
    • A factor should be selected and used for second factor verification - see verifySecondAuthFactor for more on this.

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, secondFactors) {
        if (
            error === "Second factor required" &&
            typeof secondFactors !== "undefined"
        ) {
            handleSecondFactorAuthentation(secondFactors); // you need to implement this
        } else {
            console.error("Failed to authenticate with email/password", error);
        }
    }
);

authenticateUserWithGoogle

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:

• {string} clientId - your OAuth 2.0 client ID - see here how to obtain it.
• {function} success - callback function to pass {object} credentials to as an argument. The credential object has the following properties:
  • {string} id - the identifier of a native credential object which can be used for signing in the user.
  • {string} idToken - the identiy token from Google account. Could be useful if you want to sign-in with on JS layer.
• {function} error - callback function which will be passed a {string} error message as an argument

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);
    }
);

Android

To use Google Sign-in in your Android app you need to do the following:

• Add the SHA-1 fingerprint of your app's signing key to your Firebase project
• Enable Google Sign-in in the Firebase console

For details how to do the above, see the Google Sign-In on Android page in the Firebase documentation.

Server side verification

Once the id token has been obtained from authenticateUserWithGoogle() it can be sent to your server to get access to more information about the user's google account. However, it's recommended by Google that the id token be validated on your server before being used. You should generally not trust tokens supplied by clients without performing this validation. While you can write the code to perform this check yourself, it's strongly recommended that you use a library supplied by Google such as google-auth-library for this purpose.

The following is sample coded taken from Google documentation for performing a server side verification of an id token:

const { OAuth2Client } = require("google-auth-library");

const client = new OAuth2Client(CLIENT_ID);

async function verify() {
    const ticket = await client.verifyIdToken({
        idToken: token,
        audience: CLIENT_ID, // Specify the CLIENT_ID of the app that accesses the backend
        // Or, if multiple clients access the backend:
        //[CLIENT_ID_1, CLIENT_ID_2, CLIENT_ID_3]
    });
    const payload = ticket.getPayload();
    const userid = payload["sub"];
    // If request specified a G Suite domain:
    // const domain = payload['hd'];
}
verify().catch(console.error);

authenticateUserWithApple

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:

• {function} success - callback function to pass {object} credentials to as an argument. The credential object has the following properties:
  • {string} id - the identifier of a native credential object which can be used for signing in the user.
• {function} error - callback function which will be passed a {string} error message as an argument
• {string} locale - (Android only) the language to display Apple's Sign-in screen in.
  • Defaults to "en" (English) if not specified.
  • See the Apple documentation for a list of supported locales.
  • The value is ignored on iOS which uses the locale of the device to determine the display language.

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"
);

iOS

To use Sign In with Apple in your iOS app you need to do the following:

• Configure your app for Sign In with Apple as outlined in the Firebase documentation's "Before you begin" section
• After adding the 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"
  • Note: AFAIK there is currently no way to automate the addition of this capability

Android

To use Sign In with Apple in your Android app you need to do the following:

• Configure your app for Sign In with Apple as outlined in the Firebase documentation's "Before you begin" section

authenticateUserWithMicrosoft

Authenticates the user with a Microsoft account using Sign In with Oauth to obtain a credential that can be used to sign the user in/link to an existing user account/reauthenticate the user.

• See Firebase documentation "Authenticate Using Microsoft" section

Parameters:

• {function} success - callback function to pass {object} credentials to as an argument. The credential object has the following properties:
  • {string} id - the identifier of a native credential object which can be used for signing in the user.
• {function} error - callback function which will be passed a {string} error message as an argument
• {string} locale - (Android only) the language to display Microsoft's Sign-in screen in.
  • Defaults to "en" (English) if not specified.
  • See the Microsoft documentation for a list of supported locales.
  • The value is ignored on iOS which uses the locale of the device to determine the display language.

Example usage:

FirebasePlugin.authenticateUserWithMicrosoft(
    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 Microsoft: " + error);
    },
    "en_GB"
);

authenticateUserWithFacebook

Authenticates the user with a Facebook account using a Facebook access token to obtain a Firebase credential that can be used to sign the user in/link to an existing user account/reauthenticate the user.

• Requires a 3rd party plugin such as cordova-plugin-facebook-connect to obtain the access token via the Facebook SDK.
• See the "Before you begin" sections for pre-requisites for using Facebook authentication in your app:
  • Android
  • iOS

Parameters:

• {function} success - callback function to pass {object} credentials to as an argument. The credential object has the following properties:
  • {string} id - the identifier of a native credential object which can be used for signing in the user.
• {function} error - callback function which will be passed a {string} error message as an argument

Example usage:

facebookConnectPlugin.login(
    ["public_profile"],
    function (userData) {
        var accessToken = userData.authResponse.accessToken;
        FirebasePlugin.authenticateUserWithFacebook(
            accessToken,
            function (credential) {
                FirebasePlugin.signInWithCredential(
                    credential,
                    function () {
                        console.log("Successfully signed in with Facebook");
                    },
                    function (error) {
                        console.error("Failed to sign in with Facebook", error);
                    }
                );
            },
            function (error) {
                console.error("Failed to authenticate with Facebook", error);
            }
        );
    },
    function (error) {
        console.error("Failed to login to Facebook", error);
    }
);

authenticateUserWithOAuth

Authenticates the user with an OpenID Connect (OIDC) compliant provider to obtain a credential that can be used to sign the user in/link to an existing user account/reauthenticate the user.

• You must configure your OIDC provider in the Firebase console before using this method as outlined in the Firebase documentation;
• See Firebase documentation "Authenticate Using OpenID Connect" sections for Android and iOS for more info.

Parameters:

• {function} success - callback function to pass {object} credentials to as an argument. The credential object has the following properties:
  • {string} id - the identifier of a native credential object which can be used for signing in the user.
• {function} error - callback function which will be passed a {string} error message as an argument

Example usage:

var providerId = "oidc.provider";
var customParameters = {
    login_hint: "user@domain.com",
};
var scopes = ["openid", "profile", "email"];

FirebasePlugin.authenticateUserWithOAuth(
    function (credential) {
        console.log("Successfully authenticated with oAuth provider");
        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 oAuth provider: " + error);
    },
    providerId,
    customParameters,
    scopes
);

signInWithCredential

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:

• {object} credential - a credential object returned by the success callback of an authentication method; may have the following keys:
  • {string} id - the identifier of a native credential object which can be used for signing in the user. Present if the credential was obtained via verifyPhoneNumber() and instantVerification is true, or if another authentication method was used such as authenticateUserWithGoogle().
  • {boolean} instantVerification - true if an Android device and instant verification or auto-retrieval was used to verify the user. If true, you do not need to provide a user-entered verification. - Only present if the credential was obtained via verifyPhoneNumber()
  • {string} verificationId - the verification ID to accompany the user-entered verification code from the SMS.
    • Only present if the credential was obtained via verifyPhoneNumber() and instantVerification is false.
  • {string} code - if the credential was obtained via verifyPhoneNumber() and instantVerification is false, you must set this to the activation code value as entered by the user from the received SMS message.
• {function} success - callback function to call on successful sign-in using credentials
• {function} error - callback function which will be passed a {string} error message as an argument
  • If the error is due to the user account requiring multi-factor authentication, a second {array} argument will be passed containing a list of enrolled factors.
    • A factor should be selected and used for second factor verification - see verifySecondAuthFactor for more on this.

Example usage:

function signInWithCredential(credential) {
    FirebasePlugin.signInWithCredential(
        credential,
        function () {
            console.log("Successfully signed in");
        },
        function (error, secondFactors) {
            if (
                error === "Second factor required" &&
                typeof secondFactors !== "undefined"
            ) {
                handleSecondFactorAuthentation(secondFactors); // you need to implement this
            } else {
                console.error("Failed to sign in", error);
            }
        }
    );
}

linkUserWithCredential

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:

• {object} credential - a credential object returned by the success callback of an authentication method; may have the following keys:
  • {string} id - the identifier of a native credential object which can be used for signing in the user. Present if the credential was obtained via verifyPhoneNumber() and instantVerification is true, or if another authentication method was used such as authenticateUserWithGoogle().
  • {boolean} instantVerification - true if an Android device and instant verification or auto-retrieval was used to verify the user. If true, you do not need to provide a user-entered verification. - Only present if the credential was obtained via verifyPhoneNumber()
  • {string} verificationId - the verification ID to accompany the user-entered verification code from the SMS.
    • Only present if the credential was obtained via verifyPhoneNumber() and instantVerification is false.
  • {string} code - if the credential was obtained via verifyPhoneNumber() and instantVerification is false, you must set this to the activation code value as entered by the user from the received SMS message.
• {function} success - callback function to call on successful linking using credentials
• {function} error - callback function which will be passed a {string} error message as an argument
  • If the error is due to the user account requiring multi-factor authentication, a second {array} argument will be passed containing a list of enrolled factors.
    • A factor should be selected and used for second factor verification - see verifySecondAuthFactor for more on this.

Example usage:

function linkUserWithCredential(credential) {
    FirebasePlugin.linkUserWithCredential(
        credential,
        function () {
            console.log("Successfully linked");
        },
        function (error, secondFactors) {
            if (
                error === "Second factor required" &&
                typeof secondFactors !== "undefined"
            ) {
                handleSecondFactorAuthentation(secondFactors); // you need to implement this
            } else {
                console.error("Failed to link", error);
            }
        }
    );
}

reauthenticateWithCredential

Reauthenticates the currently signed in user with credentials obtained via an authentication method such as verifyPhoneNumber() or authenticateUserWithGoogle().

Parameters:

• {object} credential - a credential object returned by the success callback of an authentication method; may have the following keys:
  • {string} id - the identifier of a native credential object which can be used for signing in the user. Present if the credential was obtained via verifyPhoneNumber() and instantVerification is true, or if another authentication method was used such as authenticateUserWithGoogle().
  • {boolean} instantVerification - true if an Android device and instant verification or auto-retrieval was used to verify the user. If true, you do not need to provide a user-entered verification. - Only present if the credential was obtained via verifyPhoneNumber()
  • {string} verificationId - the verification ID to accompany the user-entered verification code from the SMS.
    • Only present if the credential was obtained via verifyPhoneNumber() and instantVerification is false.
  • {string} code - if the credential was obtained via verifyPhoneNumber() and instantVerification is false, you must set this to the activation code value as entered by the user from the received SMS message.
• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument

Example usage:

FirebasePlugin.reauthenticateWithCredential(
    credential,
    function () {
        console.log("Successfully reauthenticated");
    },
    function (error, secondFactors) {
        if (
            error === "Second factor required" &&
            typeof secondFactors !== "undefined"
        ) {
            handleSecondFactorAuthentation(secondFactors); // you need to implement this
        } else {
            console.error("Failed to reauthenticate", error);
        }
    }
);

unlinkUserWithProvider

Unlinks an existing Firebase user account with the specified provider ID. See the Android- and iOS-specific Firebase documentation for more info.

Parameters:

• {string} providerId - ID of provider to unlink from user account
• {function} success - callback function to call on successful unlinking of provider
• {function} error - callback function which will be passed a {string} error message as an argument

Example usage:

var providerId = "microsoft.com";
FirebasePlugin.unlinkUserWithProvider(
    providerId,
    function () {
        console.log("Successfully unlinked");
    },
    function (error) {
        console.error("Failed to unlink", error);
    }
);

registerAuthStateChangeListener

Registers a Javascript function to invoke when Firebase Authentication state changes between user signed in/signed out.

Parameters:

• {function} fn - callback function to invoke when authentication state changes
  • Will be a passed a single boolean argument which is 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")
    );
});

registerAuthIdTokenChangeListener

Registers a Javascript function to invoke when Firebase Authentication ID token changes.

This can be invoked in the following circumstances:

• When a user signs in
• When the current user signs out
• When the current user changes
• When there is a change in the current user's token

Parameters:

• {function} fn - callback function to invoke when ID token changes
  • If token is present, will be a passed a single object argument with a idToken and providerId keys.
  • If the token is not present, the function will be invoked with no arguments.

Example usage:

FirebasePlugin.registerAuthIdTokenChangeListener(function (result) {
    if (result) {
        console.log(
            "Auth ID token changed to: " +
                result.idToken +
                "; providerId: " +
                result.providerId
        );
    } else {
        console.log("Auth ID token not present");
    }
});

useAuthEmulator

Instruments your app to talk to the Firebase Authentication emulator.

Parameters:

• {string} host - hostname or IP address of the Authentication emulator.
• {integer} port - port of the Authentication emulator.
• {function} success - callback function to call on success
• {function} error - callback function which will be passed a {string} error message as an argument

Example usage:

FirebasePlugin.useAuthEmulator(
    "localhost",
    9099,
    function () {
        console.log("Using Firebase Authentication emulator");
    },
    function (error) {
        console.error(
            "Failed to enable the Firebase Authentication emulator",
            error
        );
    }
);

getClaims

Returns the entire payload claims of the ID token including the standard reserved claims as well as the custom claims (set by developer via Admin SDK).

Parameters:

• {function} success - callback function to pass claims {object} to as an argument
• {function} error - callback function which will be passed a {string} error message as an argument

Example usage:

FirebasePlugin.getClaims(
    function (claims) {
        // reserved claims
        console.log("email", claims.email);
        console.log("email_verified", claims.email_verified);
        console.log("name", claims.name);
        console.log("user_id", claims.user_id);

        //custom claims
        console.log("exampleClaimA", claims.exampleClaimA);
        console.log("exampleClaimB", claims.exampleClaimB);
    },
    function (error) {
        console.error("Failed to fetch claims", error);
    }
);

Remote Config

fetch

Fetch Remote Config parameter values for your app:

Parameters:

• {integer} cacheExpirationSeconds (optional) - cache expiration in seconds. According to the documentation the default behavior is to cache for 12 hours, so if you want to quickly detect changes make sure you set this value.
• {function} success - callback function on successfully fetching remote config
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.fetch(
    function () {
        // success callback
    },
    function () {
        // error callback
    }
);
// or, specify the cacheExpirationSeconds
FirebasePlugin.fetch(
    600,
    function () {
        // success callback
    },
    function () {
        // error callback
    }
);

activateFetched

Activate the Remote Config fetched config:

Parameters:

• {function} success - callback function which will be passed a {boolean} argument indicating whether result the current call activated the fetched config.
• {function} error - callback function which will be passed a {string} error message as an argument

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);
    }
);

fetchAndActivate

Fetches and activates the Remote Config in a single operation.

Parameters:

• {function} success - callback function which will be passed a {boolean} argument indicating whether result the current call activated the fetched config.
• {function} error - callback function which will be passed a {string} error message as an argument

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);
    }
);

resetRemoteConfig

Deletes all activated, fetched and defaults configs and resets all Firebase Remote Config settings.

Android only.

Parameters:

• {function} success - callback function to call on successful reset.
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.resetRemoteConfig(
    function () {
        console.log("Successfully reset remote config");
    },
    function (error) {
        console.error("Error resetting remote config: " + error);
    }
);

getValue

Retrieve a Remote Config value:

Parameters:

• {string} key - key for which to fetch associated value
• {function} success - callback function which will be passed a {string} argument containing the value stored against the specified key. If the expected value is of a different primitive type (e.g. boolean, integer) you should cast the value to the appropriate type.
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.getValue(
    "key",
    function (value) {
        console.log(value);
    },
    function (error) {
        console.error(error);
    }
);

getInfo

Get the current state of the FirebaseRemoteConfig singleton object:

Parameters:

• {function} success - callback function which will be passed an {object} argument containing the state info
• {function} error - callback function which will be passed a {string} error message as an argument

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);
    }
);

getAll

Returns all Remote Config as key/value pairs

Parameters:

• {function} success - callback function which will be passed an {object} argument where key is the remote config key and value is the value as a string. If the expected key value is a different primitive type then cast it to the appropriate type.
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.getAll(
    function (values) {
        for (var key in values) {
            console.log(key + "=" + values[key]);
        }
    },
    function (error) {
        console.error(error);
    }
);

setConfigSettings

Changes the default Remote Config settings:

• Fetch timeout sets how long your app should wait for new Remote Config values before timing out.
  • Useful when you don’t want your application to wait longer than X seconds to fetch new Remote Config values
• Minimum fetch interval sets the minimum interval for which you want to check for any new Remote Config parameter values.
  • Keep in mind that setting too short an interval in production might cause your app to run into rate limits.

Parameters:

• {integer} fetchTimeout - fetch timeout in seconds.
  • Default is 60 seconds.
  • Specify as null value to omit setting this value.
• {integer} minimumFetchInterval - minimum fetch inteval in seconds.
  • Default is 12 hours.
  • Specify as null value to omit setting this value.
  • Set to 0 to disable minimum interval entirely (DO NOT do this in production)
• {function} success - callback function to be call on successfully setting the remote config settings
• {function} error - callback function which will be passed a {string} error message as an argument

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);
    }
);

setDefaults

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:

• {object} defaults - object specifying the default remote config settings
  • key is the name of your Remote Config parameter
  • value is the default value
• {function} success - callback function to be call on successfully setting the remote config parameter defaults
• {function} error - callback function which will be passed a {string} error message as an argument

// 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);

Performance

setPerformanceCollectionEnabled

Manually enable/disable performance data collection, e.g. if disabled on app startup.

Parameters:

• {boolean} setEnabled - whether to enable or disable performance data collection

FirebasePlugin.setPerformanceCollectionEnabled(true); // Enables performance data collection

FirebasePlugin.setPerformanceCollectionEnabled(false); // Disables performance data collection

isPerformanceCollectionEnabled

Indicates whether performance data collection is enabled.

Notes:

• This value applies both to the current app session and subsequent app sessions until such time as it is changed.
• It returns the value set by setPerformanceCollectionEnabled().
• If automatic data collection was not disabled on app startup, this will always return true.

Parameters:

• {function} success - callback function which will be invoked on success. Will be passed a {boolean} indicating if the setting is enabled.
• {function} error - (optional) callback function which will be passed a {string} error message as an argument

FirebasePlugin.isPerformanceCollectionEnabled(
    function (enabled) {
        console.log(
            "Performance data collection is " +
                (enabled ? "enabled" : "disabled")
        );
    },
    function (error) {
        console.error(
            "Error getting Performance data collection setting: " + error
        );
    }
);

startTrace

Start a trace.

Parameters:

• {string} name - name of trace to start
• {function} success - callback function to call on successfully starting trace
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.startTrace("test trace", success, error);

incrementCounter

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:

• {string} name - name of trace
• {string} counterName - name of counter to increment
• {function} success - callback function to call on successfully incrementing counter
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.incrementCounter("test trace", "retry", success, error);

stopTrace

Stop the trace

Parameters:

• {string} name - name of trace to stop
• {function} success - callback function to call on successfully stopping trace
• {function} error - callback function which will be passed a {string} error message as an argument

FirebasePlugin.stopTrace("test trace");

Firestore

These plugin API functions provide CRUD operations for working with documents in Firestore collections.

Notes:

• Only top-level Firestore collections are currently supported - subcollections (nested collections within documents) are currently not supported due to the complexity of mapping the native objects into the plugin's JS API layer.
• A document object may contain values of primitive Javascript types string, number, boolean, array or object. Arrays and objects may contain nested structures of these types.
• If a collection name referenced in a document write operation does not already exist, it will be created by the first write operation referencing it.

addDocumentToFirestoreCollection

Adds a new document to a Firestore collection, which will be allocated an auto-generated document ID.

Parameters:

• {object} document - document object to add to collection
• {string} collection - name of top-level collection to add document to.
• {boolean} timestamp (optional) - Add 'created' and 'lastUpdate' variables in the document. Default false.
• {function} success (optional) - callback function to call on successfully adding the document. Will be passed a {string} argument containing the auto-generated document ID that the document was stored against.
• {function} error (optional) - callback function which will be passed a {string} error message as an argument.

var document = {
    a_string: "foo",
    a_list: [1, 2, 3],
    an_object: {
        an_integer: 1,
    },
};
var collection = "my_collection";

// with timestamp
FirebasePlugin.addDocumentToFirestoreCollection(
    document,
    collection,
    true,
    function (documentId) {
        console.log("Successfully added document with id=" + documentId);
    },
    function (error) {
        console.error("Error adding document: " + error);
    }
);

// without timestamp
FirebasePlugin.addDocumentToFirestoreCollection(
    document,
    collection,
    function (documentId) {
        console.log("Successfully added document with id=" + documentId);
    },
    function (error) {
        console.error("Error adding document: " + error);
    }
);

setDocumentInFirestoreCollection

Sets (adds/replaces) a document with the given ID in a Firestore collection.

Parameters:

• {string} documentId - document ID to use when setting document in the collection.
• {object} document - document object to set in collection.
• {string} collection - name of top-level collection to set document in.
• {boolean} timestamp (optional) - Add 'lastUpdate' variable in the document. Default false.
• {function} success (optional) - callback function to call on successfully setting the document.
• {function} error (optional) - callback function which will be passed a {string} error message as an argument.

var documentId = "my_doc";
var document = {
    a_string: "foo",
    a_list: [1, 2, 3],
    an_object: {
        an_integer: 1,
    },
};
var collection = "my_collection";

// with timestamp
FirebasePlugin.setDocumentInFirestoreCollection(
    documentId,
    document,
    collection,
    true,
    function () {
        console.log("Successfully set document with id=" + documentId);
    },
    function (error) {
        console.error("Error setting document: " + error);
    }
);

// without timestamp
FirebasePlugin.setDocumentInFirestoreCollection(
    documentId,
    document,
    collection,
    function () {
        console.log("Successfully set document with id=" + documentId);
    },
    function (error) {
        console.error("Error setting document: " + error);
    }
);

updateDocumentInFirestoreCollection

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:

• {string} documentId - document ID of the document to update.
• {object} document - entire document or document fragment to update existing document with.
• {string} collection - name of top-level collection to update document in.
• {boolean} timestamp (optional) - Add 'lastUpdate' variable in the document. Default false.
• {function} success (optional) - callback function to call on successfully updating the document.
• {function} error (optional) - callback function which will be passed a {string} error message as an argument.

var documentId = "my_doc";
var documentFragment = {
    a_string: "new value",
    a_new_string: "bar",
};
var collection = "my_collection";

// with timestamp
FirebasePlugin.updateDocumentInFirestoreCollection(
    documentId,
    documentFragment,
    collection,
    true,
    function () {
        console.log("Successfully updated document with id=" + documentId);
    },
    function (error) {
        console.error("Error updating document: " + error);
    }
);

// without timestamp
FirebasePlugin.updateDocumentInFirestoreCollection(
    documentId,
    documentFragment,
    collection,
    function () {
        console.log("Successfully updated document with id=" + documentId);
    },
    function (error) {
        console.error("Error updating document: " + error);
    }
);

deleteDocumentFromFirestoreCollection

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:

• {string} documentId - document ID of the document to delete.
• {string} collection - name of top-level collection to delete document in.
• {function} success - callback function to call on successfully deleting the document.
• {function} error - callback function which will be passed a {string} error message as an argument.

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);
    }
);

documentExistsInFirestoreCollection

Indicates if a document with the given ID exists in a Firestore collection.

Parameters:

• {string} documentId - document ID of the document.
• {string} collection - name of top-level collection to check for document.
• {function} success - callback function to call pass result. Will be passed an {boolean} which is true if a document exists.
• {function} error - callback function which will be passed a {string} error message as an argument.

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);
    }
);

fetchDocumentInFirestoreCollection

Fetches an existing document with the given ID from a Firestore collection.

Notes:

• If no document with the specified ID exists in the collection, the error callback will be invoked.
• If the document contains references to another document, they will be converted to the document path string to avoid circular reference issues.

Parameters:

• {string} documentId - document ID of the document to fetch.
• {string} collection - name of top-level collection to fetch document from.
• {function} success - callback function to call on successfully fetching the document. Will be passed an {object} contain the document contents.
• {function} error - callback function which will be passed a {string} error message as an argument.

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);
    }
);

fetchFirestoreCollection

Fetches all the documents in the specific collection.

Notes:

• If no collection with the specified name exists, the error callback will be invoked.
• If the documents in the collection contain references to another document, they will be converted to the document path string to avoid circular reference issues.

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.

  • Supports where, orderBy, startAt, endAt and limit filters.
    • See the Firestore documentation for more details.
  • Each filter is defined as an array of filter components:
    • where: [where, fieldName, operator, value, valueType]
      • fieldName - name of field to match
      • operator - operator to apply to match
        • supported operators: ==, <, >, <=, >=, array-contains
      • value - field value to match
      • valueType (optional) - type of variable to fetch value as
        • supported types: string, boolean, integer, double, long
        • if not specified, defaults to string
    • startAt: [startAt, value, valueType]
      • value - field value to start at
      • valueType (optional) - type of variable to fetch value as (as above)
    • endAt: [endAt, value, valueType]
      • value - field value to end at
      • valueType (optional) - type of variable to fetch value as (as above)
    • orderBy: [orderBy, fieldName, sortDirection]
      • fieldName - name of field to order by
      • sortDirection - direction to order in: asc or desc
    • limit: [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);
    }
);

listenToDocumentInFirestoreCollection

Adds a listener to detect real-time changes to the specified document.

Note: If the document contains references to another document, they will be converted to the document path string to avoid circular reference issues.

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 cache
• snapshot - a snapshot of document at the time of the change.
  • May not be present if change event is due to a metadata 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:

• {function} success - callback function to call on successfully adding the listener AND on subsequently detecting changes to that document. Will be passed an {object} representing the id or change event.
• {function} error - callback function which will be passed a {string} error message as an argument.
• {string} documentId - document ID of the document to listen to.
• {string} collection - name of top-level collection to listen to the document in.
• {boolean} includeMetadata - whether to listen for changes to document metadata.
  • Defaults to false.
  • See Events for metadata changes for more info.

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
);

listenToFirestoreCollection

Adds a listener to detect real-time changes to documents in a Firestore collection.

Note: If the documents in the collection contain references to another document, they will be converted to the document path string to avoid circular reference issues.

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 cache
  • type - specifies the change type:
    • added - document was added to collection
    • modified - document was modified in collection
    • removed - document was removed from collection
    • metadata - document metadata changed
  • snapshot - a snapshot of document at the time of the change.
    • May not be present if change event is due to a metadata 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:

• {function} success - callback function to call on successfully adding the listener AND on subsequently detecting changes to that collection. Will be passed an {object} representing the id or change event.
• {function} error - callback function which will be passed a {string} error message as an argument.
• {string} collection - name of top-level collection to listen to the document in.
• {array} filters (optional) - a list of filters to sort/filter the documents returned from your collection.
  • See fetchFirestoreCollection
• {boolean} includeMetadata (optional) - whether to listen for changes to document metadata.
  • Defaults to false.
  • See Events for metadata changes for more info.

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
);

removeFirestoreListener

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:

• {function} success - callback function to call on successfully removing the listener.
• {function} error - callback function which will be passed a {string} error message as an argument.
• {string|number} listenerId - ID of the listener to remove

FirebasePlugin.removeFirestoreListener(
    function () {
        console.log("Successfully removed listener");
    },
    function (error) {
        console.error("Error removing listener: " + error);
    },
    listenerId
);

Functions

Exposes API methods of the Firebase Functions SDK.

functionsHttpsCallable

Call a firebase Https Callable function

Parameters:

• {string} name - the name of the function
• {object} args - arguments to send to the function
• {function} success - callback function to call on successfully completed the function call. Will be passed an {object/array/string} containing the data returned by the function
• {function} error - callback function which will be passed a {string/object} error message as an argument.

var functionName = "myBackendFunction";
var args = {
    arg1: "First argument",
    arg2: "second argument",
};
FirebasePlugin.functionsHttpsCallable(
    functionName,
    args,
    function (result) {
        console.log("Successfully called function: " + JSON.stringify(result));
    },
    function (error) {
        console.error("Error calling function: " + JSON.stringify(error));
    }
);

Installations

Exposes API methods of the Firebase Installations SDK.

getInstallationId

Returns the current Firebase installation ID (FID).

Parameters:

• {function} success - callback function to call on successfully completed the function call. Will be passed the {string} Firebase installation ID.
• {function} error - callback function which will be passed a {string/object} error message as an argument.

FirebasePlugin.getInstallationId(
    function (id) {
        console.log("Got installation ID: " + id);
    },
    function (error) {
        console.error("Failed to get installation ID", error);
    }
);

getInstallationToken

Returns the JWT auth token for the current Firebase installation ID (FID).

Parameters:

• {function} success - callback function to call on successfully completed the function call. Will be passed the {string} Firebase installation token.
• {function} error - callback function which will be passed a {string/object} error message as an argument.

FirebasePlugin.getInstallationToken(
    function (token) {
        console.log("Got installation token: " + token);
    },
    function (error) {
        console.error("Failed to get installation token", error);
    }
);

getInstallationId

Deletes the current Firebase installation ID (FID).

Parameters:

• {function} success - callback function to call on successfully completed the function call.
• {function} error - callback function which will be passed a {string/object} error message as an argument.

FirebasePlugin.deleteInstallationId(
    function () {
        console.log("Deleted installation ID");
    },
    function (error) {
        console.error("Failed to delete installation ID", error);
    }
);

registerInstallationIdChangeListener

Registers a Javascript function to invoke when Firebase Installation ID changes.

iOS only.

Parameters:

• {function} fn - callback function to invoke when installation ID changes.
  • Will be a passed a single {string} argument which is the new installation ID.

Example usage:

FirebasePlugin.registerInstallationIdChangeListener(function (installationId) {
    console.log("New installation ID: " + installationId);
});

Miscellaneous

Functions unrelated to any specific Firebase SDK component.

registerApplicationDidBecomeActiveListener

Registers a Javascript function to invoke when the iOS application becomes active after being in the background.

• iOS only.

Parameters:

• {function} fn - callback function to invoke when application becomes active

Example usage:

FirebasePlugin.registerApplicationDidBecomeActiveListener(function () {
    console.log("Application became active");
});

registerApplicationDidEnterBackgroundListener

Registers a Javascript function to invoke when the iOS application is sent to the background.

• iOS only.

Parameters:

• {function} fn - callback function to invoke when application is sent to the background

Example usage:

FirebasePlugin.registerApplicationDidEnterBackgroundListener(function () {
    console.log("Application send to background");
});

Debug mode

Enable debug mode to use DebugView. You can find detailed information here

Android

1. Connect your developer Android device via USB.
2. Allow the connection on the device.
3. Open your terminal and run adb devices -l
4. If your device appears run adb shell setprop debug.firebase.analytics.app PACKAGE.NAME

Now your device is in debug Mode.

Disable it using adb shell setprop debug.firebase.analytics.app .none.

IOS

Find information here

Credits

• @robertarnesson for the original cordova-plugin-firebase from which this plugin is forked.
• @sagrawal31 and Wiz Panda for contributions via cordova-plugin-firebase-lib.
• Full list of contributors