Create cloud-messaging.md

docs/api/cloud-messaging.md

@@ -0,0 +1,136 @@
+# Cloud Messaging
+
+Firebase Cloud Messaging ([FCM](https://firebase.google.com/docs/cloud-messaging/)) allows you to send push messages at no 
+cost to both Android & iOS platforms. Assuming the installation instructions have been followed, FCM is ready to go.
+
+As the Firebase Web SDK has limited messaging functionality, the following methods within `react-native-firebase` have been
+created to handle FCM in the React Native environment.
+
+## API
+
+### subscribeToTopic(topic: string)
+
+Subscribes the device to a topic.
+
+```javascript
+firebase.messaging().subscribeToTopic('foobar');
+```
+
+### unsubscribeFromTopic(topic: string)
+
+Unsubscribes the device from a topic.
+
+```javascript
+firebase.messaging().unsubscribeFromTopic('foobar');
+```
+
+### getInitialNotification(): Promise<Object>
+
+When the application has been opened from a notification `getInitialNotification` is called and the notification payload 
+is returned. Use `onMessage` for notifications when the app is running.
+
+```javascript
+firebase.messaging().getInitialNotification()
+  .then((notification) => {
+    console.log('Notification which opened the app: ', notification);
+  });
+```
+
+### getToken(): Promise<string>
+
+Returns the devices FCM token. This token can be used in the Firebase console to send messages to directly.
+
+```javascript
+firebase.messaging().getToken()
+  .then((token) => {
+    console.log('Device FCM Token: ', token);
+  });
+```
+
+### onTokenRefresh(listener: Function<string>)
+
+On the event a devices FCM token is refreshed by Google, the new token is returned in a callback listener.
+
+```javascript
+firebase.messaging().onTokenRefresh((token) => {
+  console.log('Refreshed FCM token: ', token);
+});
+```
+
+### onMessage(listener: Function<Object>)
+
+On a new message, the payload object is passed to the listener callback. This method is only triggered when the app is
+running. Use `getInitialNotification` for notifications which cause the app to open.
+
+```javascript
+firebase.messaging().onMessage((message) => {
+  // TODO
+});
+```
+
+### createLocalNotification(notification: Object)
+
+Create a local notification from the device itself.
+
+// TODO
+
+### scheduleLocalNotification(notification: Object)
+
+Schedule a local notification to be shown on the device.
+
+### getScheduledLocalNotifications(): Promise<Array>
+
+Returns an array of all currently scheduled notifications.
+
+```javascript
+firebase.messaging().getScheduledLocalNotifications()
+  .then((notifications) => {
+    console.log('Current scheduled notifications: ', notifications);
+  });
+```
+
+### cancelLocalNotification(id: string)
+
+Cancels a location notification by ID, or all notifications by `*`.
+
+```javascript
+// Cancel all local notifications
+firebase.messaging().cancelLocalNotification('*');
+// Cancel a single local notification
+firebase.messaging().cancelLocalNotification('123');
+```
+
+### removeDeliveredNotification(id: string)
+
+Removes all delivered notifications from device by ID, or all notifications by `*`.
+
+```javascript
+// Remove all notifications
+firebase.messaging().removeDeliveredNotification('*');
+// Removes a single local notification
+firebase.messaging().removeDeliveredNotification('123');
+```
+
+### [iOS] requestPermissions()
+
+Requests app notification permissions in an Alert dialog.
+
+```javascript
+firebase.messaging().requestPermissions();
+```
+
+### [iOS] setBadgeNumber(value: number)
+
+Sets the badge number on the iOS app icon.
+
+```javascript
+firebase.messaging().setBadgeNumber(2);
+```
+
+### [iOS] getBadgeNumber(): number
+
+Returns the current badge number on the app icon.
+
+```javascript
+const badgeNumber = firebase.messaging().getBadgeNumber();
+```