# Push Notifications
Required Phonegap plugins
cordova-plugin-fcm
### Requirements for Firebase Messaging
This plugin uses Firebase cloud messaging to send out push notifications. A server key is required from the Google Firebase Cloud Messaging Service. You can sign up for an account and acquire one [here](https://firebase.google.com/).
Follow instructions below to attain a google-services.json and/or GoogleService-Info.plist file as required by the cloud builder.
**Start by first Creating a new Firebase Project**
Create a Firebase project
**Add a new App to the project**
You can add either one or more android or IOS application here. If you need push messaging for both platforms, you will need to add both versions of the application. When registering your application, make sure you use the same package ID as when you added the package to the cloud builder.
Use matching package ID as in Cloud control center
For iOS, you will also need to generate an Apple Push Notification certificate (APN) within the Certificates, Identifiers, and Profiles page. Within the FCM (Firebase console), make sure to upload those certificates as well.
Once the Apps have been registered you can get the google-services.json and GoogleService-Info.plist files. This is used in our cloud builder and sets up your app to be able to receive messages.
Download the google-services.json and GoogleService-Info.plit
In order to send notifications we need to generate a private key for the service admin SDK. If you do not have a service account setup then you will need to create one first via "Manage service account permissions" link within the settings page.
Once you have downloaded the account service key json file you can add it to the /media/lib/fcm directory under Servoy solution. Name the file **services.json** so it can be referenced by the **sendFCMPushMessage** method.
Generate and keep the .json file in a safe place.
## API Documentation
### Method Summary
#### onTokenRefresh
Get a callback every time a token is generated, including the initial generation.
**Params**
| Type | Name | Summary | Required |
| -------- | --------------- | ------------------- | -------- |
| Function | successCallback | on success callback | Optional |
| Function | errorCallback | on error callback | Optional |
#### getToken
Generate a token
**Params**
| Type | Name | Summary | Required |
| -------- | --------------- | ------------------- | -------- |
| Function | successCallback | on success callback | Optional |
| Function | errorCallback | on error callback | Optional |
#### subscribeToTopic
Subscribe to a topic and get notifications All devices are subscribed automatically to 'all' and 'ios' or 'android' topic respectively. Topic String must match the following regular expression: "\[a-zA-Z0-9-\_.\~%]{1,900}".
**Params**
| Type | Name | Summary | Required |
| -------- | --------------- | ------------------- | -------- |
| Function | successCallback | on success callback | Optional |
| Function | errorCallback | on error callback | Optional |
| String | Topic | Topic to subscribe | Required |
#### unubscribeFromTopic
unSubscribe from a topic and no longer receive notifications. All devices are subscribed automatically to 'all' and 'ios' or 'android' topic respectively. Topic String must match the following regular expression: "\[a-zA-Z0-9-\_.\~%]{1,900}".
**Params**
| Type | Name | Summary | Required |
| -------- | --------------- | ------------------------- | -------- |
| Function | successCallback | on success callback | Optional |
| Function | errorCallback | on error callback | Optional |
| String | Topic | Topic to unsubscribe from | Required |
#### onNotification
Define the behavior receiving a notification.
**Params**
| Type | Name | Summary | Required |
| -------- | ---------------------- | ----------------------------- | -------- |
| Function | onNotificationCallback | when notification is received | Optional |
| Function | successCallback | on success callback | Optional |
| Function | errorCallback | on error callback | Optional |
#### **Sending a push notification message**
To send notifications we can use **scopes.phonegap.sendFCMPushMessage** method. This requires adding fcm binaries from the svyphonegap releases page to /medias/lib/fcm directory. You also need to include the services.json file from above in the same directory.
**Params**
| Type | Name | Summary | Required |
| ------ | ------- | ---------------------------------------- | -------- |
| String | topic | Send to subscribed notification topic | Required |
| String | title | Notification Tile | Optional |
| String | body | Notification Body | Optional |
| String | channel | Notification Channel (ex. urgent\_alert) | Optional |
## Example Usage
```javascript
//initialize and generate a notification token.
plugins.svyphonegapPush.getToken(null, null);
//subscribe to notifications where topic = svyMobile.
plugins.svyphonegapPush.subscribeToTopic(null, null, 'svyMobile')
//when receiving a notification display a message if UI is visible.
plugins.svyphonegapPush.onNotification(showMessage, null, null)
//Use a callback function to designate behavior when notification is received.
function showMessage(data) {
//if application is in background
if (data.wasTapped) {
plugins.dialogs.showInfoDialog('INFO', 'Notification received while UI closed.')
} else {
//if application is active
plugins.dialogs.showInfoDialog('INFO', 'Notification received while UI visible.')
}
}
//Sending a message
scopes.phonegap.sendFCMPushMessage('svyMobile','INFO','This is a message','urgent_alert')
```
