Tabris.js Firebase Plugin

The tabris-plugin-firebase plugin project provides a Tabris.js API to receive firebase cloud messages. The plugin allows to receive notification data when the app is in the foreground or to automatically display a notification when the app is not running or in the background. Currently only Android is supported with iOS support coming in the future.

Example

The following snippet shows how the tabris-plugin-firebase plugin can be used to receive a cloud message in a Tabris.js app.

console.log('Token to send to server: ' + firebase.Messaging.token);

firebase.Messaging.on('change:token',
    (messaging, token) => console.log('Server token refreshed: ' + token));

firebase.Messaging.on('message',
    (messaging, data) => console.log('Received message data: ' + JSON.stringify(data)));

console.log('Message data from app cold start: ' + firebase.Messaging.launchData);

A more elaborate example can be found in the example folder. It provides a Tabris.js cordova project that demonstrates the various features of the tabris-plugin-firebase integration. When building the example project make sure to run npm install inside its www folder to fetch the Tabris.js dependencies.

To send a message from the server side a curl command similar to the following POST request can be used:

curl -X POST -H "Authorization: key=<server-key>" -H "Content-Type: application/json" -d '{
    "to": "<token>",
    "data": {
      "title": "New data",
      "text": "The new data arrived",
      "payload": "custom data"
    }
  }
' https://fcm.googleapis.com/fcm/send

Integrating the plugin

Using the plugin follows the standard cordova plugin mechanism. The Tabris.js website provides detailed information on how to integrate custom plugins in your Tabris.js app.

Add the plugin to your project

The plugin can be added like any other cordova plugin. Either via the cordova plugin add command or as an entry in the apps config.xml (recommended):

<!-- THE PLUGIN IS NOT YET AVAILABLE ON NPMJS.COM -->
<!-- <plugin name="tabris-plugin-firebase" spec="1.0.0" /> -->

To fetch the latest development version use the GitHub url:

<plugin name="tabris-plugin-firebase" spec="https://github.com/eclipsesource/tabris-plugin-firebase" />

Provide the firebase credentials

To enable the firebase support in your app, you have to provide the google-services.json file which contains the apps ids and credentials. The file can be obtained from the firebase console.

To make the google-services.json file available to the tabris-plugins-firebase you have to place it in the same folder as your apps config.xml file. If the file is missing the plugin will print an appropriate error message.

Notification icon (optional)

An Android notification icon can be provided via the plugin variable ANDROID_NOTIFICATION_ICON. To configure an icon the resource id of an Android drawable inside the Android platforms res folder has to be specified. A build hook can be used to copy the notification icon from your project into the android platform res folder. See the example project for a snippet to get you started.

The icon can be configured inside your apps config.xml:

<plugin name="tabris-plugin-firebase" spec="1.0.0">
  <variable name="ANDROID_NOTIFICATION_ICON" value="@drawable/ic_notification" />
</plugin>

Alternatively the image can be added during the cordova plugin add command:

cordova plugin add <path-to-tabris-firebase-plugin> --variable ANDROID_NOTIFICATION_ICON=`icon_drawable_name`

When no notification icon is specified, the outline of the app icon is used.

Send message with notification from server

When the server sends a message to a device it can create two types of messages: "notification" messages and "data" messages. Messages that contain a notification key in its json payload are treated as "notification" message. More details of the differences between "notification" and "data" messages can be found in the firebase documentation.

The key difference for this plugin is that "notification" messages create their notification automatically when the app is in the background. Tapping on the notification does not forward the notification data to the app.

To create a notification that also delivers its data to the app, when the notification is tapped, a regular "data" notification has to be created. A "data" message does not have a key notification.

To configure the notification several properties can be set:

id : number
title : string
text : string

The following message send from a server would create a notification similar to the screenshot above:

POST /fcm/send HTTP/1.1
Host: fcm.googleapis.com
Authorization: key=<server-key>
Content-Type: application/json

{
  "to": "<token>",
  "data": {
    "title": "New data available",
    "text": "The new data can be used in a multitude of ways",
    "payload": "custom data"
  }
}

Note that the json object above does not contain a notification key. It only provides the to key to declare the message receiver and the data payload send to the app.

Using the same id for multiple messages updates an existing notification on the users device. Omitting the id creates a random id on the device so that each message results in a unique notification.

API documentation

The firebase messaging API is represented as the global object firebase.Messaging.

`Messaging`

Properties

All Messaging properties are read only.

`instanceId` : string

A stable identifier that uniquely identifies the app installation. Note that on Android the instance id can become invalid as noted in the documentation.

`token` : string

A registration token to be used on the server side to address an app installation. The registration token is usually available but can change during the apps lifetime. To get notified of a registration token updates you should listen for change:token events. When resetting the instanceId, the token is not available until the change:token event fired.

`launchData` : object

Contains the cloud message data when the app is cold started from a notification. There are two scenarios of message data delivery:
1. When the app is in the foreground (or running in the background and the user taps on the notification) the message event callback is invoked.
2. In case the app process is not running and the app is freshly launched (cold started) from a notification, the data contained within that notification is available in the launchData object.
The recommended way to make sure your app receives all messaging data is to check the firebase.Messaging.launchData object on app startup and to register for the message event to receive follow-up messages.

Events

`change:instanceId`

The change:instanceId event is fired asynchronously when the resetInstanceId() method is invoked.

Parameter:

messaging : Messaging
- The Messaging object which allows to interact with firebase cloud messaging
instanceId : string
- The new instanceId of the app

`change:token`

The change:token event is fired when the current registration token has changed. Check the firebase documentation for details when that might be the case.

Parameter:

messaging : Messaging
- The Messaging object which allows to interact with firebase cloud messaging
token : string
- The new registration token to send to the server

`message`

The message event is fired when a cloud message is received by a running app. This can either be while the app is in the foreground or the user clicks on a notification while the app is running in the background. To get the message data while the app is cold launched from a notification see the launchData property.

Parameter:

messaging : Messaging
- The Messaging object which allows to interact with firebase cloud messaging
data : object
- The message data object as send from the server side

Methods

`resetInstanceId()`

Invalidates the current instanceId and creates a new one asynchronously. To be notified when a new instanceId is available you should listen for the change:instanceId event. Resetting the instanceId also resets the associated registration token. A change:token event will be fired once a new token is available.

Compatibility

Compatible with Tabris.js 2.0.0

Development of the plugin

While not required by the consumer of the plugin, this repository provides Android specific development artifacts. These artifacts allow to more easily consume the native source code when developing the native parts of the plugin.

Android

The project provides a gradle based build configuration, which also allows to import the project into Android Studio.

In order to reference the Tabris.js specific APIs, the environment variable TABRIS_ANDROID_CORDOVA_PLATFORM has to point to the Tabris.js Android Cordova platform root directory.

export TABRIS_ANDROID_CORDOVA_PLATFORM=/home/user/tabris-android-cordova

The environment variable is consumed in the gradle projects build.gradle file.

Copyright

Published under the terms of the BSD 3-Clause License.

cpetrov/tabris-plugin-firebase

Tabris.js Firebase Plugin

Example

Integrating the plugin

Add the plugin to your project

Provide the firebase credentials

Notification icon (optional)

Send message with notification from server

API documentation

Messaging

Properties

instanceId : string

token : string

launchData : object

Events

change:instanceId

Parameter:

change:token

Parameter:

message

Parameter:

Methods

resetInstanceId()

Compatibility

Development of the plugin

Android

Copyright

`Messaging`

`instanceId` : string

`token` : string

`launchData` : object

`change:instanceId`

`change:token`

`message`

`resetInstanceId()`