Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nickersoft/push-fcm-plugin

Official Firebase Cloud Messaging plugin for Push.js v1.0 :fire:
https://github.com/nickersoft/push-fcm-plugin

fcm firebase framework javascript js notifications plugin push pushjs

Last synced: 2 months ago
JSON representation

Official Firebase Cloud Messaging plugin for Push.js v1.0 :fire:

Awesome Lists containing this project

README 

        
# Push.js FCM Plugin



## What is FCM?

FCM, otherwise known as Firebase Cloud Messaging, is a free feature of the Google Firebase Platform, a collection of services for building scalable, effective web services. FCM allows web servers to send direct messages to a group of subscribers using ServiceWorkers. This means that by using this plugin, Push.js can now send targeted push notifications to a user's desktop without your website being open! Finally! :tada::tada::tada:



Though, keep in mind this is the first plugin for Push.js, ever. Expect a few bumps and potholes.



## Installing

Just like Push itself, this module is easily installable via NPM or Bower:



```bash

$ npm install push-fcm-plugin --save

$ bower install push-fcm-plugin --save 

```



## How to Use

### Configuring

With Push.js, managing FCM on your site becomes incredibly easy. To begin, you need to configure FCM Push's SafeConfig: Head on over to your [Firebase console](https://console.firebase.google.com/) and add a new project. Once the project is created, click on it and then click "Add Firebase to your web app". Select the configuration map from the generated code in the popup window and add it to your JavaScript file. Then, add the map to Push's FCM configuration using the `config()` method. Your finally code should look something like this:



```javascript

var config = {

    apiKey: "",

    authDomain: "",

    databaseURL: "",

    projectId: "",

    storageBucket: "",

    messagingSenderId: ""

};



Push.config({

    FCM: config

});

```



Lastly, add a `manifest.json` file to the root of your web server with the following contents:

  

```json

{

    "//": "Some browsers will use this to enable push notifications.",

    "//": "It is the same for all projects, this is not your project's sender ID",

    "gcm_sender_id": "103953800507"

}

```



then import it into your HTML:



```html



```



This sender ID is required in order to tell Firebase your website allows messages to be pushed to it. **Do not change the above ID.** It is the same for all Firebase projects, regardless of who you are or what you've built. 



### Using with AMD or CommonJS

If you use AMD or CommonJS to load Push, you'll have to manually install the plugin. 



For AMD:



```javascript

define(['push', 'pushjs-fcm'], function (Push, PushFCM) {

    Push.extend(PushFCM);

});

```



For CommonJS:



```javascript

const Push = require('pushjs');

const PushFCM = require('pushjs-fcm');



Push.extend(PushFCM);

```



### Initializing

To initialize FCM, just call:



```javascript

Push.FCM();

```



And that's it! You can then use the returned promise to run additional functions:



```javascript

Push.FCM().then(function(FCM) {

    FCM.getToken().then(function(token) {

        console.log("Initialized with token " + token);

    }).catch(function(tokenError) {

       throw tokenError; 

    });

}).catch(function(initError) {

   throw initError; 

});

```



The available functions are as follows:



| Function                | Description                                                                                                         | Returns                      |

|-------------------------|---------------------------------------------------------------------------------------------------------------------|------------------------------|

| `getToken()`            | generates a new Instance ID token or retrieves the current one if it already exists                                 | Promise(token, error)        |

| `deleteToken()`         | deletes the current token                                                                                           | Promise(deletedToken, error) |

| `isTokenSentToServer()` | denotes whether the current token has been sent to the server via `sendTokenToServer()`  (see "Additional Options") | Boolean                      |



### Additional Options

The FCM SafeConfig has a few additional options you can pass to it:



- `serviceWorkerLocation`: Specifies directory containing the `firebase-messaging-sw` ServiceWorker script. May need to

change if Push has been installed via NPM or Bower. The default is `./`.

- `onTokenFetched(token)`: Called when a new Instance ID token is retrieved

- `onTokenFetchedError(error)`: Called if an error occurs while retrieving a new Instance ID token

- `onPermissionRequired()` Called when permission is required to retrieve an Instance ID

- `onPermissionGranted()`: Called when said permission is granted

- `onPermissionDenied()`: Called when said permission is denied

- `onMessage(payload)`: Called when a new message is received

- `sendTokenToServer(token)`: Function that sends the given token to your server for future use 

- `onTokenDeleted(deletedToken)`: Called when the current token is deleted

- `onTokenDeletedError(error)`: Called if an error occurs while deleting the current token



### Sending Server-side Notifications

To send a notification to a given Instance ID from your server, simply make a POST request to `https://fcm.googleapis.com/fcm/send` with the following data:



Header

```text

Authorization: key=

Content-Type: application/json

```



Body

```json

{ 

  "notification": {

    "title": "Notification Title",

    "body": "Notification Body",

    "click_action" : "http://example.com"

  },

  "to" : ""

}

```



You can find your server key by going to your project console on Firebase, clicking the gear icon on the right sidebar, selecting "Project Settings" and going to the "Cloud Messaging" tab. For more information on messaging types, read Google's [documentation on the topic](https://firebase.google.com/docs/cloud-messaging/concept-options#notifications).



### Writing Your Own Plugin

Documentation on writing plugins will be coming the official Push.js docs soon!