morinel · cr0ybot · Nov 17, 2016 · May 30, 2018 · Jun 6, 2018 · Jun 7, 2018
diff --git a/README.md b/README.md
@@ -1,24 +1,43 @@
-# Titanium Module for Google Cloud Messaging Push Notifications for Android #
+# Titanium Module for Firebase Cloud Messaging Push Notifications for Android #
 
-A Titanium module for registering a device with Google Cloud Messaging and handling push notifications sent to the device.
+A Titanium module for registering a device with Firebase Cloud Messaging and handling push notifications sent to the device.
 
 [![gitTio](http://gitt.io/badge.png)](http://gitt.io/component/nl.vanvianen.android.gcm)
 
 Read the [documentation](https://github.com/morinel/gcmpush/blob/master/documentation/index.md).
 
-To build, create a `build.properties` file with the following content:
+## Quickstart
+
+1. Install this module using Axway Studio or via the CLI with `gittio install nl.vanvianen.android.gcm`
+2. Set up your [Firebase project](https://console.firebase.google.com/).
+3. Download the `google-services.json` file and put it in `PROJECT_FOLDER/app/assets/android/` (or `PROJECT_FOLDER/Resources/android/` for non-Alloy projects).
+4. You are ready to receive Android push notifications! Check the [documentation](https://github.com/morinel/gcmpush/blob/master/documentation/index.md) for further instructions and examples.
+
+## GCM to FCM Migration
+
+If you are upgrading this module to version 3.0+, you will need to migrate to Firebase (Google will discontinue GCM in April 2019):
+
+1. In the [Firebase console](https://console.firebase.google.com/), select __Add Project__
+2. Select your GCM project from the list of existing Google Cloud Projects, and select __Add Firebase__
+3. In the Firebase welcome screen, select __Add Firebase to your Android App__
+4. Provide your package name (and optionally an SHA1 from your keystore) and select __Add App__. A new `google-services.json` file for your Firebase app is downloaded. Place this file in `PROJECT_FOLDER/app/assets/android/` (or `PROJECT_FOLDER/Resources/android/` for non-Alloy projects).
+5. Update to version 3.0+ of this module
+6. Check the [Upgrade Guide](https://github.com/morinel/gcmpush/blob/master/documentation/index.md#version-3-upgrade-guide) for instructions about what needs to be altered in your code
+
+## Build
+
+To build this module, you will need the prerequisites described in the [Android Module Project documentation](https://docs.appcelerator.com/platform/latest/#!/guide/Android_Module_Project).
+
+Then, simply `cd` into the module directory and run the following command:
 
 ```
-titanium.platform=/Users/###USER###/Library/Application Support/Titanium/mobilesdk/osx/7.0.0.GA/android
-android.platform=/Users/###USER###/Library/Android/sdk/platforms/android-26
-google.apis=/Users/###USER###/Library/Android/sdk/add-ons/addon-google_apis-google-23
-android.ndk=/Users/###USER###/Library/Android/ndk
+$ appc ti build -p android --build-only
 ```
 
-Make sure your paths are correct for your system setup. Then run:
+OR, if you are using just the open-source Titanium SDK:
 
 ```
-$ appc run -p android --build-only
+$ ti build -p android --build-only
 ```
 
 A zip file will be created in the `dist` folder.
diff --git a/build.properties b/build.properties
diff --git a/build.xml b/build.xml
diff --git a/documentation/index.md b/documentation/index.md
@@ -1,17 +1,142 @@
-# Titanium Module for Google Cloud Messaging Push Notifications for Android #
+# Titanium Module for Firebase Cloud Messaging Push Notifications for Android #
 
 [![gitTio](http://gitt.io/badge.png)](http://gitt.io/component/nl.vanvianen.android.gcm)
 
-A Titanium module for registering a device with Google Cloud Messaging and handling push notifications sent to the device. Both push notifications and topic subscriptions are supported.
+A Titanium module for registering a device with Firebase Cloud Messaging and handling push notifications sent to the device. Both push notifications and topic subscriptions are supported.
 
-1. Install the module as usual in Appcelerator Studio by downloading the [zip file](https://github.com/morinel/gcmpush/releases/download/1.5/nl.vanvianen.android.gcm-android-1.5.zip) or use ```gittio install nl.vanvianen.android.gcm```
+1. Install the module as usual in Appcelerator Studio by downloading the zip file of the [latest release](https://github.com/morinel/gcmpush/releases/latest) or use `gittio install nl.vanvianen.android.gcm`
+1. Set up your [Firebase project](https://console.firebase.google.com/).
+1. Download the `google-services.json` file and put it in `PROJECT_FOLDER/app/assets/android/` (or `PROJECT_FOLDER/Resources/android/` for non-Alloy projects).
 1. Refer to the examples for possibilities.
-1. Send a server push notification with your preferred server-side technology to the registrationId returned while registering your device.
+1. Send a server push notification with your preferred server-side technology to the registrationId returned from calling `registerPush()`.
 1. The callback you specified will then be called.
 
 This module does not require any tiapp.xml properties, all configuration is done in Javascript.
 
-## Example server-side code to send a push notification ##
+
+## Version 3 Ugrade Guide ##
+
+The hardest part about upgrading this module to v3 is the external configuration of Firebase. Most of your code should work the same, with one notable addition. You may need to add a `registration` callback in the `registerPush` parameters which handles updating your stored devide token (AKA registration ID) with whatever push notification service you are using. If you are using Firebase directly for sending push notifications, this won't be necessary.
+
+You can also remove the `senderId` option in the `registerPush` parameters, as that is handled with the `google-services.json` file.
+
+
+## Register your app for push notifications ##
+
+See [this example](https://github.com/morinel/gcmpush/blob/master/example/app.js).
+
+It is not required to define `firebaseFile` or `firebaseConfig` if you have put your `google-services.json` file in the correct place. However, these options are available for advanced configurations. If your json file is named differently or is located in a subfolder, you must pass the path to the `firebaseFile` option.
+
+Alternatively, you can copy the JSON out of the file and pass it directly with the `firebaseConfig` option. This is useful if you have different Firebase projects for dev and production—you can pass different JSON depending on the build type, and if you're using Alloy you can add it to your config.json file and pass `Alloy.CFG.firebase`.
+
+```
+var gcm = require("nl.vanvianen.android.gcm");
+
+gcm.registerPush({
+    /* Firebase config file (if you've renamed it or if it's in a subfolder) */
+    firebaseFile: 'somepath/google-services.json',
+    /* Firebase config JSON */
+    firebaseConfig: {
+        # ...
+    },
+    notificationSettings: {
+        sound: 'mysound.mp3', /* Place sound file in app/platform/android/res/raw/mysound.mp3 */
+        smallIcon: 'notification_icon.png',  /* Place icon in app/platform/android/res/drawable/notification_icon.png */
+        largeIcon: 'appicon.png',  /* Same */
+        vibrate: true,  /* Whether the phone should vibrate */
+        insistent: true,  /* Whether the notification should be insistent */
+        group: 'MyNotificationGroup',  /* Name of group to group similar notifications together */
+        localOnly: false,  /* Whether this notification should be bridged to other devices */
+        priority: +2,  /* Notification priority, from -2 to +2 */
+        bigText: false,
+        /* You can also set a static value for title, message, or ticker. If you set a value here, the key will be ignored. */
+        // title: '',
+        // message: '',
+        // ticker: ''
+        /* Add LED flashing */
+        ledOn: 200,
+        ledOff: 300
+        /* Android O channels */
+        channelId: 'my_channel',
+        channelName: 'My Channel'
+    },
+    success: function (event) {
+        Ti.API.debug("Push registration success: " + JSON.stringify(event));
+
+        /* Add code to send event.registrationId to your server */
+    },
+    error: function (event) {
+        Ti.API.debug("Push registration error: " + JSON.stringify(event));
+        alert(event.error);
+    },
+    callback: function (event) {
+        Ti.API.debug("Push callback: " + JSON.stringify(event));
+        /* Called when a notification is received and the app is in the foreground */
+
+        var dialog = Ti.UI.createAlertDialog({
+            title: 'Push received',
+            message: JSON.stringify(event.data),
+            buttonNames: ['View','Cancel'],
+            cancel: 1
+        });
+        dialog.addEventListener("click", function(event) {
+            dialog.hide();
+            if (event.index == 0) {
+                /* Do stuff to view the notification */
+            }
+        });
+        dialog.show();
+    },
+    registration: function (event) {
+        Ti.API.debug("Registration callback: " + JSON.stringify(event));
+        /* Called when the registration token has changed */
+
+        /* Add code to send event.registrationId to your server */
+    }
+});
+```
+
+
+## Notification settings for push notifications ##
+
+See the [example](https://github.com/morinel/gcmpush/blob/master/example/app.js) for an overview of how to specify the below settings:
+
+1. **smallIcon**: the tiny icon shown at the top of the screen, see this [stackoverflow question](http://stackoverflow.com/questions/28387602/notification-bar-icon-turns-white-in-android-5-lollipop) for details. The file should be placed in the ```platform/android/res/drawable``` directory.
+1. **largeIcon**: the large icon shown in the notification bar. If not specified your appicon will be used. The file should be placed in the ```platform/android/res/drawable``` directory.
+1. **sound**: the sound file to play while receiving the notification or 'default' for the default sound. The sound file should be placed in the ```platform/android/res/raw``` directory.
+1. **vibrate** (true / false): whether vibration should be on, default false.
+1. **insistent** (true / false): whether the notification should be [insistent](http://developer.android.com/reference/android/app/Notification.html#FLAG_INSISTENT), default false.
+1. **group**: name of group to group similar notifications together, default null.
+1. **localOnly** (true / false): whether this notification should be bridged to other devices (false) or is only relevant to this device (true), default true.
+1. **backgroundOnly** (true / false): whether the app should only be notified when it's in the background, default false.
+1. **priority**: (integer) specifies the priority of the notification, should be between [PRIORITY_MIN](http://developer.android.com/reference/android/support/v4/app/NotificationCompat.html#PRIORITY_MIN) and [PRIORITY_MAX](http://developer.android.com/reference/android/support/v4/app/NotificationCompat.html#PRIORITY_MAX), default 0.
+1. **bigText** (true / false): whether this notification should use the [bigText style](http://developer.android.com/reference/android/app/Notification.BigTextStyle.html), default false.
+1. **titleKey** (string): specify a custom key name for the notification title sent by the server, default ```title```
+1. **messageKey** (string): specify a custom key name for the notification message sent by the server, default ```message```
+1. **tickerKey** (string): specify a custom key name for the notification ticker text sent by the server, default ```ticker```
+1. **title** (string): specify a static title for the notification (server data will be ignored)
+1. **message** (string): specify a static message for the notification (server data will be ignored)
+1. **ticker** (string): specify a static ticker for the notification (server data will be ignored)
+1. **ledOn** (integer): the number of ms the LED should be on while flashing, see  [javadoc](http://developer.android.com/reference/android/app/Notification.html#ledOnMS)
+1. **ledOff** (integer): the number of ms the LED should be off while flashing, see [javadoc](http://developer.android.com/reference/android/app/Notification.html#ledOffMS)
+1. **notificationId** (integer): a (unique) integer to identify the notification. If specified, subsequent notifications will not override the previous one.
+1. **channelId** (string): [Android O] a unique identifier for the channel the notification belongs to, should be lower-case with underscores
+1. **channelName** (string) [Android O] a human-readable name for the notification channel
+
+
+The settings sound, vibrate, insistent, group, localOnly, priority, bigText and notificationId can also be set as data in the push message being received (see the server-side example above).
+
+If the app is not active when the notification is received, use gcm.getLastData() to retrieve the contents of the notification and act accordingly to start or resume the app in a suitable way. If you're done, call gcm.clearLastData(), otherwise the same logic will happen when resuming the app again, see the [example](https://github.com/morinel/gcmpush/blob/master/example/app.js).
+
+
+## Testing notifications in your app ##
+
+There currently seems to be an issue which causes the registration token to be invalidated when rebuilding the app after having already built & installed. If you are not receiving notifications during development, you may need to uninstall the app from your device and rebuild/reinstall.
+
+
+## Example server-side Java code to send a push notification ##
+
+**THIS EXAMPLE NO LONGER APPLIES WITH FCM**
 
 Use the following dependency:
 
@@ -59,44 +184,10 @@ public void sendPush() {
 ```
 
 
-## Register your app for push notifications ##
-
-See [this example](https://github.com/morinel/gcmpush/blob/master/example/app.js).
-
-
-## Notification settings for push notifications ##
-
-See the [example](https://github.com/morinel/gcmpush/blob/master/example/app.js) for an overview of how to specify the below settings:
-
-1. **smallIcon**: the tiny icon shown at the top of the screen, see this [stackoverflow question](http://stackoverflow.com/questions/28387602/notification-bar-icon-turns-white-in-android-5-lollipop) for details. The file should be placed in the ```platform/android/res/drawable``` directory.
-1. **largeIcon**: the large icon shown in the notification bar. If not specified your appicon will be used. The file should be placed in the ```platform/android/res/drawable``` directory.
-1. **sound**: the sound file to play while receiving the notification or 'default' for the default sound. The sound file should be placed in the ```platform/android/res/raw``` directory.
-1. **vibrate** (true / false): whether vibration should be on, default false.
-1. **insistent** (true / false): whether the notification should be [insistent](http://developer.android.com/reference/android/app/Notification.html#FLAG_INSISTENT), default false.
-1. **group**: name of group to group similar notifications together, default null.
-1. **localOnly** (true / false): whether this notification should be bridged to other devices (false) or is only relevant to this device (true), default true.
-1. **backgroundOnly** (true / false): whether the app should only be notified when it's in the background, default false.
-1. **priority**: (integer) specifies the priority of the notification, should be between [PRIORITY_MIN](http://developer.android.com/reference/android/support/v4/app/NotificationCompat.html#PRIORITY_MIN) and [PRIORITY_MAX](http://developer.android.com/reference/android/support/v4/app/NotificationCompat.html#PRIORITY_MAX), default 0.
-1. **bigText** (true / false): whether this notification should use the [bigText style](http://developer.android.com/reference/android/app/Notification.BigTextStyle.html), default false.
-1. **titleKey** (string): specify a custom key name for the notification title sent by the server, default ```title```
-1. **messageKey** (string): specify a custom key name for the notification message sent by the server, default ```message```
-1. **tickerKey** (string): specify a custom key name for the notification ticker text sent by the server, default ```ticker```
-1. **title** (string): specify a static title for the notification (server data will be ignored)
-1. **message** (string): specify a static message for the notification (server data will be ignored)
-1. **ticker** (string): specify a static ticker for the notification (server data will be ignored)
-1. **ledOn** (integer): the number of ms the LED should be on while flashing, see  [javadoc](http://developer.android.com/reference/android/app/Notification.html#ledOnMS)
-1. **ledOff** (integer): the number of ms the LED should be off while flashing, see [javadoc](http://developer.android.com/reference/android/app/Notification.html#ledOffMS)
-1. **notificationId** (integer): a (unique) integer to identify the notification. If specified, subsequent notifications will not override the previous one.
-
-
-The settings sound, vibrate, insistent, group, localOnly, priority, bigText and notificationId can also be set as data in the push message being received (see the server-side example above).
-
-If the app is not active when the notification is received, use gcm.getLastData() to retrieve the contents of the notification and act accordingly to start or resume the app in a suitable way. If you're done, call gcm.clearLastData(), otherwise the same logic will happen when resuming the app again, see the [example](https://github.com/morinel/gcmpush/blob/master/example/app.js).
-
-
-
 ## Example server-side code to send message to a topic ##
 
+**THIS EXAMPLE NO LONGER APPLIES WITH FCM**
+
 ```java
 import org.apache.commons.io.IOUtils;
 import org.json.JSONException;