This plugin brings push notifications, analytics, event tracking, crash reporting and more from Google Firebase to your Cordova project. Android and iOS supported.
- Download your Firebase configuration files, GoogleService-Info.plist for ios and google-services.json for android.
- Create a zipped folder with the name "google-services.zip" and put both configuration files inside.
- On the "www" folder, create a folder called + ".firebase" and place the zip inside.
- My Project/
config.xml
platforms/
plugins/
www/
com.example.application.appid.firebase/
google-services.zip/
google-services.json <--
GoogleService-Info.plist <--
See https://support.google.com/firebase/answer/7015592 for details how to download the files from firebase.
This plugin uses a hook (before plugin install) that copies the configuration files to the right place, namely platforms/ios/<My Project>/Resources for ios and platforms/android for android.
Note that 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.
- Have your sound files ready with the correct extension (.wav, .mp3 for Android / .wav, .caf for iOS) and rename them "push_sound".
- Prepare a zipped folder called "push_sound.zip" with the sound files.
- Add the zip folder to the "www" folder.
- My Project/
platforms/
plugins/
www/
push_sound.zip/
push_sound.wav <--
push_sound.caf <--
Get the device token (id):
window.FirebasePlugin.getToken(function(token) {
// save this server-side and use it to push notifications to this device
console.log(token);
}, function(error) {
console.error(error);
});
Note that token will be null if it has not been established yet
Register for token changes:
window.FirebasePlugin.onTokenRefresh(function(token) {
// save this server-side and use it to push notifications to this device
console.log(token);
}, function(error) {
console.error(error);
});
This is the best way to get a valid token for the device as soon as the token is established
Register notification callback:
window.FirebasePlugin.onNotificationOpen(function(notification) {
console.log(notification);
}, function(error) {
console.error(error);
});
Notification flow:
- App is in foreground:
- User receives the notification data in the JavaScript callback without any notification on the device itself (this is the normal behaviour of push notifications, it is up to you, the developer, to notify the user)
- App is in background:
- User receives the notification message in its device notification bar
- User taps the notification and the app opens
- User receives the notification data in the JavaScript callback
Notification icon on Android:
Grant permission to recieve push notifications (will trigger prompt):
window.FirebasePlugin.grantPermission();
Check permission to recieve push notifications:
window.FirebasePlugin.hasPermission(function(data){
console.log(data.isEnabled);
});
Set a number on the icon badge:
window.FirebasePlugin.setBadgeNumber(3);
Set 0 to clear the badge
window.FirebasePlugin.setBadgeNumber(0);
Get icon badge number:
window.FirebasePlugin.getBadgeNumber(function(n) {
console.log(n);
});
Subscribe to a topic:
window.FirebasePlugin.subscribe("example");
Unsubscribe from a topic:
window.FirebasePlugin.unsubscribe("example");
Unregister from firebase, used to stop receiving push notifications. Call this when you logout user from your app. :
window.FirebasePlugin.unregister();
Log an event using Analytics:
window.FirebasePlugin.logEvent("select_content", {content_type: "page_view", item_id: "home"});
Set the name of the current screen in Analytics:
window.FirebasePlugin.setScreenName("Home");
Set a user id for use in Analytics:
window.FirebasePlugin.setUserId("user_id");
Set a user property for use in Analytics:
window.FirebasePlugin.setUserProperty("name", "value");
Request a verification ID and send a SMS with a verification code. Use them to construct a credential to sign in the user (in your app).
- https://firebase.google.com/docs/auth/android/phone-auth
- https://firebase.google.com/docs/reference/js/firebase.auth.Auth#signInWithCredential
- https://firebase.google.com/docs/reference/js/firebase.User#linkWithCredential
NOTE: This will only works on physical devices.
iOS will return: credential (string) Android will return: credential.verificationId (object and with key verificationId) credential.instantVerification (boolean)
You need to use device plugin in order to access the right key.
IMPORTANT NOTE: Android supports auto-verify and instant device verification. Therefore in that cases it doesn't make sense to ask for sms code as you won't receive any. Also, verificationId will be false in this case. In order to sign the user in you need to check credential.instantVerification, if it's true, skip the SMS Code entry, call your backend server (sorry, the only way to succeed with this plugin) and pass over the phonenumber as param to identify the user (via ajax for example, using any endpoint to your backend).
When using node.js Firebase Admin-SDK, follow this tutorial:
Pass back your custom generated token and call
firebase.auth().signInWithCustomToken(customTokenFromYourServer);instead of
firebase.auth().signInWithCredential(credential)
YOU HAVE TO COVER THIS PROCESS, OR YOU WILL HAVE ABOUT 5% OF USERS STUCKING AT YOUR SCREEN, NO RECEIVING ANYTHING If this process is too complex for you, use this awesome plugin
It's not perfect but it fits for the most usecases and doesn't require to call your endpoint, as it has native phone auth support.
window.FirebasePlugin.verifyPhoneNumber(number, timeOutDuration, function(credential) {
console.log(credential);
// ask user to input verificationCode:
var code = inputField.value.toString();
var verificationId = credential.verificationId;
var credential = firebase.auth.PhoneAuthProvider.credential(verificationId, code);
// sign in with the credential
firebase.auth().signInWithCredential(credential);
// call if credential.instantVerification was true (android only)
firebase.auth().signInWithCustomToken(customTokenFromYourServer);
// OR link to an account
firebase.auth().currentUser.linkWithCredential(credential)
}, function(error) {
console.error(error);
});
To use this auth you need to configure your app SHA hash in the android app configuration on firebase console. See https://developers.google.com/android/guides/client-auth to know how to get SHA app hash.
Setup your push notifications first, and verify that they are arriving to your physical device before you test this method. Use the APNs auth key to generate the .p8 file and upload it to firebase. When you call this method, FCM sends a silent push to the device to verify it.
Fetch Remote Config parameter values for your app:
window.FirebasePlugin.fetch(function () {
// success callback
}, function () {
// error callback
});
// or, specify the cacheExpirationSeconds
window.FirebasePlugin.fetch(600, function () {
// success callback
}, function () {
// error callback
});
Activate the Remote Config fetched config:
window.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);
});
Retrieve a Remote Config value:
window.FirebasePlugin.getValue("key", function(value) {
console.log(value);
}, function(error) {
console.error(error);
});
// or, specify a namespace for the config value
window.FirebasePlugin.getValue("key", "namespace", function(value) {
console.log(value);
}, function(error) {
console.error(error);
});
NOTE: byte array is only available for SDK 19+ Retrieve a Remote Config byte array:
window.FirebasePlugin.getByteArray("key", function(bytes) {
// a Base64 encoded string that represents the value for "key"
console.log(bytes.base64);
// a numeric array containing the values of the byte array (i.e. [0xFF, 0x00])
console.log(bytes.array);
}, function(error) {
console.error(error);
});
// or, specify a namespace for the byte array
window.FirebasePlugin.getByteArray("key", "namespace", function(bytes) {
// a Base64 encoded string that represents the value for "key"
console.log(bytes.base64);
// a numeric array containing the values of the byte array (i.e. [0xFF, 0x00])
console.log(bytes.array);
}, function(error) {
console.error(error);
});
Get the current state of the FirebaseRemoteConfig singleton object:
window.FirebasePlugin.getInfo(function(info) {
// the status of the developer mode setting (true/false)
console.log(info.configSettings.developerModeEnabled);
// 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);
});
Change the settings for the FirebaseRemoteConfig object's operations:
var settings = {
developerModeEnabled: true
}
window.FirebasePlugin.setConfigSettings(settings);
Set defaults in the Remote Config:
// define defaults
var defaults = {
// map property name to value in Remote Config defaults
mLong: 1000,
mString: 'hello world',
mDouble: 3.14,
mBoolean: true,
// map "mBase64" to a Remote Config byte array represented by a Base64 string
// Note: the Base64 string is in an array in order to differentiate from a string config value
mBase64: ["SGVsbG8gV29ybGQ="],
// map "mBytes" to a Remote Config byte array represented by a numeric array
mBytes: [0xFF, 0x00]
}
// set defaults
window.FirebasePlugin.setDefaults(defaults);
// or, specify a namespace
window.FirebasePlugin.setDefaults(defaults, "namespace");
Start a trace.
window.FirebasePlugin.startTrace("test trace", success, error);
To count the performance-related events that occur in your app (such as cache hits or retries), add a line of code similar to the following whenever the event occurs, using a string other than retry to name that event if you are counting a different type of event:
window.FirebasePlugin.incrementCounter("test trace", "retry", success, error);
Stop the trace
window.FirebasePlugin.stopTrace("test trace");
Enable/disable analytics collection
window.FirebasePlugin.setAnalyticsCollectionEnabled(true); // Enables analytics collection
window.FirebasePlugin.setAnalyticsCollectionEnabled(false); // Disables analytics collection
Download your container-config json file from Tag Manager and add a resource-file node in your config.xml.
....
<platform name="android">
<content src="index.html" />
<resource-file src="GTM-5MFXXXX.json" target="assets/containers/GTM-5MFXXXX.json" />
...
The plugin will use notification_icon from drawable resources if it exists, otherwise the default app icon will is used.
To set a big icon and small icon for notifications, define them through drawable nodes.
Create the required styles.xml files and add the icons to the
<projectroot>/res/native/android/res/<drawable-DPI> folders.
The example below uses a png named "ic_silhouette.png", the app Icon (@mipmap/icon) and sets a base theme.
From android version 21 (Lollipop) notifications were changed, needing a seperate setting.
If you only target Lollipop and above, you don't need to setup both.
Thankfully using the version dependant asset selections, we can make one build/apk supporting all target platforms.
<projectroot>/res/native/android/res/values/styles.xml
<?xml version="1.0" encoding="utf-8" ?>
<resources>
<!-- inherit from the holo theme -->
<style name="AppTheme" parent="android:Theme.Light">
<item name="android:windowDisablePreview">true</item>
</style>
<drawable name="notification_big">@mipmap/icon</drawable>
<drawable name="notification_icon">@mipmap/icon</drawable>
</resources>
and
<projectroot>/res/native/android/res/values-v21/styles.xml
<?xml version="1.0" encoding="utf-8" ?>
<resources>
<!-- inherit from the material theme -->
<style name="AppTheme" parent="android:Theme.Material">
<item name="android:windowDisablePreview">true</item>
</style>
<drawable name="notification_big">@mipmap/icon</drawable>
<drawable name="notification_icon">@drawable/ic_silhouette</drawable>
</resources>
On Android Lollipop and above you can also set the accent color for the notification by adding a color setting.
<projectroot>/res/native/android/res/values/colors.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
<color name="primary">#FFFFFF00</color>
<color name="primary_dark">#FF220022</color>
<color name="accent">#FF00FFFF</color>
</resources>