Cordova Firebase Plugin

This Cordova plugin brings push notifications, analytics, event tracking, crash reporting and more from Google Firebase to your Cordova project.

Demo

Preparation for iOS

When working with push notification for iOS, APNs authentication key or APNs certificate is required. For this reason, we will need to create one of them first. In this page, we will show you how to create Development APNs cerficate for testing on iOS Debug build.

For release build, Production APNs Certificate is required.

Assuming that you have already Apple Developer Program, please follow the instruction below on how to create a Development APNs certificate.

  1. From Apple Developer page, go to Account.

  2. Select Certificates, Identifiers & Profiles.

  3. An App ID with push notification enabled is required when creating an APNs certificate. Therefore, let’s start creating one. Under Identifiers section, go to App IDs and click on + button in the upper-right corner.

  4. Fill in the following information for the App ID such as:

    • App Description: Input your app name here (e.g. Cordova Firebase Demo)
    • Explicit ID: Select this option because Wildcard App ID is not allowed for push notification. Input a unique identifier for your app (e.g. io.monaca.firebase).
  5. Scroll down to App Services section and tick Push Notifications option. Then, click Continue.

  6. After that, you will be redirected to a Confirm your App ID page. click Register to complete this process.

  7. Now, you should be back to the iOS App IDs page. Select on the App ID you’ve just created and click Edit.

  8. Scroll down to Push Notifications section, click on Create Cerficate under Development SSL Certificate.

  9. Click Continue.

  10. After that, click Choose File to browse your CSR file. You can get this file from Monaca Cloud IDE by going to Config → iOS Build Settings . Then, click on Generate Key and CSR. After creating the CRS file, download it by clicking on Export button.

  11. Next, click Continue again. When the certificate is ready, you can start downloading it. Keep the file, we will need it for Firebase configuration in the upcoming section.

Configuring Firebase for Push Notification

  1. Go to Firebase console.

  2. Sign in with your Google account to enter the console.

  3. Click on Add project.

  4. Fill in the project information and click CREATE PROJECT. Then, you will be redirected to the Project Overview page.

After project creation, we can start configuring the push notification the project for specific platform.

For iOS

  1. Go to Project setting.

  2. Under General section, click ADD APP and select iOS.

  3. Enter your iOS Bundle ID (You can find that by going to Config → iOS App Settings ). Then, click REGISTER APP.

  4. Download GoogleService-Info.plist file and place it in the root folder of your project. After that, click CONTINUE.

  5. You will see instructions on how to add the Firebase SDK into our project. However, we are not developing the app natively, we can skip this step. So just click click CONTINUE to proceed. Then, click click FINISH to complete the configuration. After that, you should see your iOS app in the Firebase overview page.

  6. Now, it’s time to add APNs certificates into this project. Go to Project setting and select CLOUD MESSAGING.

  7. Scroll down to iOS app configuration section and upload APNs authentication key or APNs certificates.

That’s it! Now, you are done with iOS configuration.

For Android

  1. Go to Project setting.

  2. Under General section, click ADD APP and select Android.

  3. Enter your package name (You can find that by going to Config → Android App Settings ). Then, click REGISTER APP.

  4. Download google-services.json file and place it in the root folder of your project. After that, click CONTINUE.

  5. You will see instructions on how to add the Firebase SDK into our project. However, we are not developing the app natively, we can skip this step. So just click click FINISH to complete the configuration. After that, you should see your Android app in the Firebase overview page.

Adding the Plugin in Monaca IDE

  1. From the IDE menu, go to Config → Manage Cordova Plugins .

  2. Click on Import Cordova Plugin button. Then, you can choose to import the plugin using a ZIP file or URL/Package Name.

Usage

After importing the plugin into the project, you can start generate a token for your device and set an event for when a user opens a notification. Please make sure to call the plugin API after the Cordova is loaded.

document.addEventListener("deviceready", function(){
    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);
    });

    // Get notified when a token is refreshed
    window.FirebasePlugin.onTokenRefresh(function(token) {
        // save this server-side and use it to push notifications to this device
        console.log("Refresh to get new token: " + token);
    }, function(error) {
        alert(error);
    });

    // Get notified when the user opens a notification
    window.FirebasePlugin.onNotificationOpen(function(notification) {
        console.log(JSON.stringify(notification));
        alert("The notification is open!");
    }, function(error) {
        console.error(error);
    });    
}, false);

API References

In this page, we only describe some main APIs used in our Demo. For a complete API references, please refer to here.

getToken()

Get the device token. The token will be null if it has not been established yet

window.FirebasePlugin.getToken();

Return Value

  • Promise

Example

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

onTokenRefresh()

Get notified when a token is refreshed. This is the best way to get a valid token for the device as soon as the token is established.

window.FirebasePlugin.onTokenRefresh();

Return Value

  • Promise

Example

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

onNotificationOpen()

Get notified when the notification is open.

window.FirebasePlugin.onNotificationOpen();

Return Value

  • Promise

Example

window.FirebasePlugin.onNotificationOpen(function(notification) {
    console.log(JSON.stringify(notification));
    alert("The notification is open!");
}, function(error) {
    console.error(error);
});    

hasPermission()

Check permission to recieve push notifications.

window.FirebasePlugin.hasPermission();

Return Value

  • Promise

Example

window.FirebasePlugin.hasPermission(function(data){
    if (data.isEnabled)
        alert("Permission to receive notification is granted.");
    else
        alert("Permission to receive notification is NOT granted.");
});

grantPermission() (iOS only)

Grant permission to recieve push notifications for iOS (will trigger a prompt if the permission has not been granted yet).

window.FirebasePlugin.grantPermission();

Return Value

  • Promise

Example

window.FirebasePlugin.grantPermission(function(){
    alert("Permission is granted for iOS");    
}, function(error){
    alert(error);
});

setBadgeNumber()

Set a number on the icon badge.

window.FirebasePlugin.setBadgeNumber(badgeNumber);

Parameter

Name Type Description
badgeNumber Number The number on the icon badge

Return Value

  • Promise

Example

After running setting the badge number, close the app. Then, you will see the badge number appear on your app icon. If you want to remove the number, please set it to 0.

window.FirebasePlugin.setBadgeNumber(5);

getBadgeNumber()

Get icon badge number.

window.FirebasePlugin.getBadgeNumber();

Return Value

  • Promise

Example

window.FirebasePlugin.getBadgeNumber(function(n) {
        alert("Badge Number is " + n);
    });

unregister()

Unregister from firebase to stop receiving push notifications. Call this when you logout user from your app.

window.FirebasePlugin.unregister();

Return Value

  • Promise

Example

window.FirebasePlugin.unregister(function(){
    alert("Stop receiving push notifications."); 
}, function(error){
    alert(error);
});

setScreenName()

Set the name of the current screen in Analytics.

window.FirebasePlugin.setScreenName(screenName);

Parameter

Name Type Description
screenName String Screen name

Return Value

  • Promise

Example

var page="FirebaseHome";
window.FirebasePlugin.setScreenName(page);
alert(page + " screen is tracked.");

setUserId()

Set a user id for use in Analytics.

window.FirebasePlugin.setUserId(id);

Parameter

Name Type Description
id String A unique identifier, associated with that particular user, must be sent with each hit

Return Value

  • Promise

Example

//user ID for testing purpose
var myUserId="35009a79-1a05-49d7-b876-2b884d0f825b";
window.FirebasePlugin.setUserId("user_id");
alert("UserID is set to: " + myUserId);